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Licensing Requirements fdr Software Developers 

Apple has a low-cost licensing program, whidi permits developers of software 
for the Lisa to incorporate Apple-developed libraries and object code files 
into their products. Both in-house and external distribution require a license. 
Before distributing any products that incorporate Apple software, please 
contact Software Licensing at the acWress below for both licensing and 
technical informatim. 



©1983 by Apple Computer, Inc. 
20525 Mariani Avenue 
CXipertino, California 95014 
(408) 996-1010 



Apple, Lisa, and the Apple logo are trademarks of Apple Computer, Inc. 

Simultaneously (xiblished in the USA and Canada. 

Reorder Apple Product #A6D0101 (Complete Pascal pack^) 



#A6L0111 (Manuals only) 



Customer Satisfaction 

If you discover physical defects in the manuals distributed with a Lisa prochjct 
or in the media on which a software product is distributed, Apple will replace 
the documentation or media at no charge to you during the 90-day period 
after you purchased the product. 



Product Revisions 

Unless you have purchased the product update service available through ycwr 
authorized Lisa dealer, Apple cannot guarantee that you will receive notice of 
a revision to Xhs software described in this manual, even if you have returned 
a registration card received with the product You should check periodically 
with your autlrorized Lisa ctealer. 



Limitation on Warranties and Liability 

All implied warranties concerning this marxial and media, including implied 
warranties of merchantability and fitness for a particular purpose, are limited 
in duration to ninety (90) days from the date of original retail purchase of this 
product 

Even though Apple has tested the software described in this manual and 
reviewed its contents, neither /^le nor its software suppliers make any 
warranty or representation, either express or implied, with respect to this 
manual or to the software described in this manual, their quality, performance, 
merchantability, or fitness for any particular purpose. As a result, this 
software and manual are sold "as is," and you the purchaser are assuming the 
entire risk as to their quality and performance. 

In no event will Apple or its software suppliers be li^le for direct, indirect, 
special, incictental, or consequential damages resulting from any defect in the 
software or manual, even if they have been advised of the possibility of such 
damages. In particular, they shall have no liability for any programs or data 
stored in or used with Apple products, including the costs of recovering or 
reproducing these prograns or data. 

The wananty and remedies set forth above are exclusive and In lieu of all 
others, oral or written, express or implied No Apple dealer, agent or 
employee is authorized to make any modification, extension or addition to this 
warranty. 

Some states do not allow the exclusion or limitation of implied warranties or 
liability for incidental or consecpjential damages, so the above limitation or 
exclusicBi may not apply to you. This warranty gives you specific legal rights, 
and you may also have other ri^ts that vary from state to state. 
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License and Copyright 

This mamal and the software (computer programs) descritred in it are copy- 
righted by Apple or by Af^le's software suppliers, with all rigits reserved, aid 
they are covered by the Lisa Software License Agreement signed by each Lisa 
owner. Lfrider the copyri^t laws end the License Agreement, this mgnual or 
the programs may rrat be cqjied, in whole or in part, without the written 
consent of Apple, except in the normal use of the software or to m^e a 
backup copy. This exception does not allow copies to be made for others, 
whether or not sold, but all of the material purchased (with all backup copies) 
may be sold, given, or loaned to other persons if they agree to be bound by 
the provisions of the License AgreemenL Copying includes translating into 
another lar^uage or format 

You may use the software on any computer owned by you, but extra copies 
cannot be made for this purpose. For some products, a multiuse license may 
be purchased to allow the software to be used on more than one computer 
owned by the purchaser, including a shared-disk system. (Contact your 
authorized Lisa dealer for more information on multiuse licenses.) 
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Preface 



This manual Is Intended for Pascal programmers. It describes an implemen- 
tation of Pascal for the Lisa computer. The compiler and code generator 
translate Pascal source text to MC68000 object code. 

The language is reasonably compatible with Apple II and Apple III Pascal. See 
Appendix A for a discussion of the differences between these forms of Pascal. 

In addition to providing nearly all the features of standard Pascal, as described 
in the Pascal User Manual arxt Report (Jensen and Wirth), this Pascal provides 
a variety of extensions. These are summarized in Appendix A. They include 
32-bit integers, an otherwise clause in case statements, procedural and 
functional parameters with type-checked parameter lists, and the • operator 
for obtaining a pointer to an object. The real arithmetic conforms to many 
aspects of the proprased IEEE standard for single-precision arithmetic. 

Operating Environment 

The compiler win operate In any standard Lisa hardware configuration; this 
manual assurmes the Workshop software environment. 

Related Documents 

Pascal User Manual aid Report, Jensen and Wirth, Springer- Verlag 1975. 

Workshop User's Guide for the Lls^ Apple Computer, Inc. 1983. 
Other Lisa documentation. 

Definitions 

For the purposes of this manual the following definitions are used: 

• Error: Either a run-time error or a compiler error. 

• Scc^: The body of text for which the declaration of an identifier or 
label is valid. 

• Undefined: The value of a variable or function when the variable does not 
necessarily have a meaningful value of its type assigned to It 

• Unspecified: A value or action or effect that, although possibly 
well-defined, is not specified and may not be the same in all cases or for 
all versions or conflgijratlons of the system. Any programming construct 
that leads to an unspecified result or effect is not supported. 

Notation and Syntax Diagrams 

All numbers in this manual are in decimal notation, except where hexadecimal 
notation Is specifically indicated. 

Throughout this manual, bold-face type is used to distinguish Pascal text from 
English text. For example, sqi(n div 16) represents a fragment of a Pascal 
program. Sometimes the same word appears both in plain text and in 



xiii 

029-0393-A 



Pasca] Reference Manual 



Preface 



bold-face; for example, "The declaration of a Pascal procedure Deglns with 
the word procedure." 

Italics are used when technical terms are Introduced. 

Pascal syntax is specified by diagrams. For example, the following diagram 
gives the syntax for an identifier: 



Identifier 


^ 


letter 












k> 




"P* 








"\ 












letter 


^ -^ 








^ 














digit 


tf ^ 






^ 
















\ 


underscore 


^ 





Start at the left and follow the arrows through the diagram. Numerous paths 
are possible. Every path that begins at the left and ends at the arrow-head on 
the right is valid, and represents a valid way to construct an identifier. The 
boxes traversed by a path through the diagram represent the elements that can 
be used to construct an identifier. Thus the diagram embodies the following 
rules: 

• An identifier must begin with a letter, since the first arrow goes directly to 
a twx containing the name "letter." 

• An Identifier might consist of nothing but a single letter, since there is a 
path from this box to the arrow-head on the right, without going through 
any more boxes. 

• The initial letter may be followed by another letter, a digits or an 
underscore, since there are branches of the path that lead to these boxes. 

• The initial letter may be followed h^^ any number of letters, digits, or 
underscores, since there is a loop in the path. 

A word contained in a rectangular box may be a name for an atomic element 
like "letter" or "digit," or it may be a name for some other syntactic 
construction that is specified by another diagram. The name in a rectangular 
box is to be replaced by an actual instance of the atom or construction that it 
represents, e.g. "3" for "digit" or "countei" for "variable-reference". 

Pascal syfWols, such as reserved words, operators, and punctuation, are 
bold-face and are enclosed in circles or ovals, as in the following diagram for 
the construction of a compound-statement: 

compound-statement 



-» (^begin) - 



r 



statement 

=0^ 



T 



<^> 
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Text In a circle or oval represents itself, and is to be written as snown (except 
that capitalization of letters is not significant). In tne diagram above, the 
semicolon and the words begin and end are symbols. The word "statement- 
refers to a construction that has its own syntax diagram. 

A compound-statement consists of the reserved word begin, followed by any 
number of statements separated by semicolons, followed by the reserved word 
end. (As will be seen in Chapter 6, a statement may be null; thus begin end is 
a valid compound-statement.) 
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Manual 

Chapter Release Note 

Workshop The character set in the Appendix should show the full 
Appendix B International Lisa Character set, because this is now supported 

by the workshop screen and for printing to a dot-nnatrix printer. 

(A new page B-1 is attached; take a moment now to make the 

substitution.) Printing ASCII characters to a daisy wheel printer 

is supported for the following print wheels: 

• Gothic, 15 pitch 

• Prestige Elite, 12 pitch 

• Courier, 10 pitch 

• Boldface/Executive, PS. 

Printing ASCII characters to a daisy wheel printer is not 
supported for the three print wheels with Modem type styles. 
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If a variable T is defined as TrPACKED ARRAY[0..lOO] OF 
0..255, the statement Ttl] :- 255 Is not accepted by the connpller. 
Use TEMP :- 255; T[l] :- TEMP; as a workaround. The same is 
true for all subranges from 0..128 to 0..255 and for all constant 
values from 128 to 255. 

If a USES statement including the $U compiler option is 
followed on the same line by a comment, the trailing comma of 
the statement must be separated from the opening brace of the 
statement by a blank; otherwise, the code will be incorrectly 
parsed. Example: 

USES {$U foo-obj} unitljcomment} BAD 
{$U bar-obj) unltZ; 

USES {$U foo.obj} unitl, {comment} OK 
{#U bar.obj} unlt2; 

The GXRef utility accepts a maximum of 4095 procedure names. 



You cannot exit the ChangeSeg utility by typing <CR> in 
response to the first prompt line, 'File to Change*. You nnust 
type <ESC><CR>. 
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Tokens are the smallest meaningful units of text in a Pascal program; 
structurally^ they correspond to the words in an English sentence. The tokens 
of Pascal are classified into special symbols, identifiers, numbers, labels, and 
quoted string constants 

The text of a Pascal program consists of tokens and separators;^ separator is 
either a bl&ik or a comment Two adjacent tokens must be separated by one 
or more separators, if Doth tokens are identifiers, numbers, or reserved words. 

No separaton can be embedded within tokens, except in quoted string 
constants. 

1.1 Character Set and Special Symbols 

The character set used by Pascal on the Lisa is 8-bit extended ASCII, with 
characters represented by numeric codes in the range from to 255. 

Letters, digits, hex-digits, and blanks are subsets of the character set: 

• The letters are those of the English alphabet, A through Z and a through z. 

• The digits are the Arabic numerals through 9; the hex-digits are the 
Arabic numerals through 9, the letters A through F, and the letters a 
through f. 

• The blanks are the space character (ASCII 32), the horizontal tab character 
(ASCII 9), and the CR character (ASCII 13). 

Special symbols and reserved words are tokens having one or more fixed 
meanings. The following single characters are special symbols: 

*-*/ = <>[]..():;"=•{}$ 

The following character pairs are special symbols: 
<> <= >= := ., (» ») 

The following are the reserved words: 



and 


end 


label 


program 


until 


array 


file 


methods* 


record 


uses 


begin 


for 


mod 


repeat 


var 


case 


function 


nil 


set 


while 


const 


goto 


not 


string 


with 


creation* 


if 


of 


subclass* 




div 


implementation 


or 


then 




downto 


in 


otherwise 


to 




do 


interface 


packed 


type 




else 


intrinsic* 


procedure 


unit 





1-1 



Pascal Reference Manual 



Tokens & Constants 



The reserved words marked with asterisks are reserved for future use. 
Corresponding upper and lower case letters are equivalent in reserved words. 
Only tne first 8 characters of a reserved word are significant 

1.2 Identifiers 

Identifiers serve to denote constants, types, variables, procedures, functions, 
units and programs, and fields in records. Identifiers can be of any length, but 
only the first 8 characters are significant. Corresponding upper and lower case 
letters are equivalent in identifiers. 



identifier 



*• letter 









\ 


letter 


rt ^ 


^ 






digit 


^ -^ 










\ 


underscore 


^ 



NOTE 



The first 8 Characters of an identifier must not match the first 8 char- 
acters of a reserved word. 



Examples of icmtifiers: 



Rome 



They 



gcd SUH getjayte 

1.3 Directives 

Directives are words that have special meanings in particular contexts, 
are not reserved and can be used as identifiers in other contexts. For 
example, the word forward is Interpreted as a directive If it occurs 
immediately after a procedure-heading or function-heading, but in any other 
position it Is interpreted as an identifier. 

1.4 Numbers 

The usual decimal notation is used for numbers that are constants of the data 
types integer, longint, and real (see Section 3.1.1). Also, a hexadecimal integer 
constant uses the $ character as a prefix (1-4 digits for integer, 5-8 digits for 
longint). 



cfim't-semjerK^ 



Z 



digit 



T 



hex-dJQJt-semj&Tce 



c 



hex-digit 



J 
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unsianect-inteaer 




digit-sec|uence 



hex-digit-sequence 



J 



sign 



O- 




unsigned-real 





n 




kii. 


^ uiyR~S6qu6nce ^ ^\^.y^ uigii-S6quenoc| -v^ /" ^ 


V Vw 


scale-fact 


nr-^ 






or 








scale- factor ^/p\ 




-sequence 




V ^{Z) ^^ ^ 


"^ uigii 




W^yJ ^ sign -^ 


^ 


^ 




vS/ 




utmyned-nuntUei ^ . ^ . . 




^^ ► unsigneu-inieger 




I 




^•* unsigned-real ~ 




^ 








sionea-number ^ nncinnnn 


number 




■^ /" ^ unsignea- 




^H^ sign -^ 







The letter E or e preceding the scale in an unsigned-real means "times ten to 
the power of". 

Examples of numtjers: 

1 +100 -0.1 5E-3 87.35e+8 $ft05D 

Note that 5E-3 means 5x10"^, and 87.35e*8 means 87.35x10^. 
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1.5 Labels 

A label is a digit-sequence in the range from through 9999. 

1.6 Quoted String Constants 

A quoted-string-constant is a sequence of zero or more characters, all on one 
line of the program source text and enclosed by apostrophes. Currently, the 
maximum number of characters is 255. A quoted-string-constant with nothing 
between the apostrophes denotes the null string. 

If the quoted-string-constant is to contain an apostrophe, this apostrophe must 
be written twice. 



c^ted-stfir^-caTst&jt 



O 



"C 



string-character 



^ 



►0-* 



string-cnaracter 



-^ 



any chm except Q orOn 



T 



\i)~Kl)" 



Exarrples of quoted-strlng-constants: 
•Pascal* 'THIS IS A STRING' 

'A* *.* ••• 



•Don"t worry!' 



All string values have a length attribute (see Section 3.1.1.6). In the case of a 
string constant value the length is fixed; it is equal to the actual number of 
characters in the string value. 

1.6.1 Quoted Character Constants 

Syntactically, a quoted-character-constant is simply a quoted-string-constant 
whose length is exactly 1. 



quotea-cnaracter-constant ^Qy^ \ string-character h ^Q-t^ 



A quoted-character-constant is compatible with any char-type or string-type; 
that is, it can be used either as a character value or as a string value. 
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1.7 Constant Declarations 

A constant-declaration defines an identifier to denote a constant^ within the 
block that contains the declaration. The scope of a constant-identifier (see 
Chapter 2) does not include its own declaration. 



constant-declaration 



identifier — ^\z) — ^ constant — ►(T) — ► 



constant 



"T 



^^^^^ 



"^^ signed-number 



^ 



quoted-string 



^ quoted-char 



constant-identifier 



^ 



■> 



k. 



NOTE 



A constant-identifier is an identifier that has already been declared to 
denote a constant. 



A constant-identifier following a sign must denote a value of type integer, 
longlnt, or real. 

1.8 comments and Compiler commands 

The constructs: 

{ any text not containing right-brace } 

(» any text not containing star-right-paren *) 

are called cmvnents 

A compiler command is a comment that contains a $ character immediately 
after the { or (* that begins the comment The $ character is followed by the 
mnemonic of the compiler command (see Chapter 12). 

Apart from the effects of compiler commands, the substitution of a blank for a 
comment does not alter the meaning of a program. 

A comment cannot be nested within another comment formed with the same 
kind of delimiters. However, a comment formed with {...} delimiters can be 
nested within a comment formed with (*...*) delimiters, and vice versa. 
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2.2.3 Position of Declaration within Its Block 2-3 

2.2.4 Redeclaration within a Block 2-3 

2.2.5 Identifiers of Standard Objects 2-4 
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2.1 Definition of a Block 

A £>Jo€k consists of declarations and a statement-part Every block is part of 
a procedure-declaration a function-declaration^ a program, or a unit. All 
identifiers and labels that are declared in a particular block are Joca/ to that 
block. 



&/VCA 






""^^ constant-declaration-part 



label-declaration-part 



D 



^ 
^ 

^ 



type-declaration-part 



''"^ variable-declaration-part 



^ 

''H» procedure-and-function-declaration-part 



D 



^ statement-part 



The J3DeJ-cfecJar3t/o/7-p3rt tieclares all labels that mark statements in the 
corresponding statement-part. Each label must mark exactly one statement in 
the statement-part. 



■cfecJaratJon-pait 
—» ( label ) - 



7 — n_l§5HL) — ^ 



>©- 



label 



!► digit-sequence 
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The const&it-c/eclaraUon-part contains all constant-declarations local to the 
block. 

a»istant-iieclamtfof7-part 



^const^ 



Z 



constant-declaration 



J 



The type-cf&claratjon-part conX^im all type-declarations local to the block. 
type-declamtion-part 



<^>-^^^^^^j 



The variable-cleclaratJon-panmviX^Xm all variable-declarations local to the 
block. 



vari^le-ctE€lafaU(Xi-part 

— <^ 



I 



variable-declaration 



J 



The pjvcecfuw-and~flncUon-c/eclaratIon-partconi'a\[\z all procedure and 
function declarations local to the block. 



pixxxxkJw-&Ki-nMK)Uai-declaFaUon-p^rt 
■>! procedure-declaration 






g 



function-declaration 



The staterrmit-part^&:X^\'^% the algorithmic actions to be executed upon an 
activation of the block. 



statement-part 



^ compound-statement 
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NOTE 

At run time, all variables declared within a particular block have 
unspecified values each time the statement-part of the block is entered. 

2.2 Rules of Scope 

This chapter discusses the scope of objects i^//y?//7 ttie program or unit In whicti 
they are defined See Chapter 9 for the scope of objects defined in the 
interface-part of a unit and referenced in a host program or unit. 

2.2.1 Scope of a Declaration 

The appearance of an identifier or label in a declaration defines the identifier 
or label. All corresponding occurrences of the identifier or label must be 
within the scope of this declaration. 

This scope is the block that contains the declaration, and all blocks enclosed 
by that block except as explained in Section 2.2.2 below. 

2.2.2 Redeclaration in an Enclosed Block 

Suppose that outer is a block, and inner is another block that is enclosed 
within outer. If an identifier declared in block outer has a further declaration 
in block inner, then block inner and all blocks enclosed by inner are excluded 
from the scope of the declaration in block outer. (See Appendix B for some 
odd cases.) 

2.2.3 Position of Declaration within Its Block 

The declaration of an identifier or label must precede all corresponding 
occurrences of that identifier or label in the program text— i.e., identifiers and 
labels cannot be used until after they are declared. 

There is one exception to this rule: The base-type of a pointer-type (see 
Section 3.3) can be an identifier that has not yet been declared. In this case, 
the identifier must be declared somewhere in the same type-declaration-part 
in which the pointer-type occurs. (See Appendix B for some odd cases.) 

Z2.4 Redeclaration within a Block 

An identifier or label cannot be declared more than once in the outer level of 
a particular block, except for record field identifiers. 

A record field identifier (see Sections 3.2.2, 4.3, and 4.3.2) is declared within a 
record-type. It is meaningful only in combination with a reference to a 
variable of that record-type. Therefore a field identifier can be declared 
again within the same block, as long as it is not declared again at the same 
level within the same record-type. Also, an identifier that has been declared 
to denote a constant, a type, or a variable can be declared again as a record 
field identifier in the same block. 
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2.2.5 Identifiers of Standard Objects 

Pascal on the Lisa provides a set of standard (predeclared) constants^ types, 
procedures, and functions. The identifiers of these objects behave as if they 
were declared in an outermost block enclosing the entire program; thus their 
scope includes the entire program. 
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A type is used in declaring variables; it determines the set of values whicn 
those variables can assume, and the operations that can be performed upon 
them. A type-cfeclaration associates an identifier with a type. 



type-declaration 



identifier 



O 



type 



<^ 



tj^. 



simple-type 



v.. 



structured-type 



^-# pointer-type 



:l. 



The occurrence of an identifier on the left-hand side of a type-declaration 
declares it as a type-Identifier for the block In which the type-declaration 
occurs. The scope of a type-identifier does not include its own declaration, 
except for pointer-types (see Sections 2.2.3 and 3.3). 

To help clarify the syntax description with some semantic hints, the following 
terms are used to distinguish identifiers according to what they denote. 
Syntactically, all of them mean simply an identifier: 

simple-type-identifier 

structured-type-identifier 

pointer-type-identifier 

ordinal-type-identifier 

real-type-identifier 

string-type-identifier 

In other words, a simple-type-identifier is any identifier that Is declared to 
denote a simple type, a structured-type-identifier is any identifier that is 
declared to denote a structured type, and so forth. A simple-type-identifier 
can be the predeclared identifier of a standard type such as integer, boolean, 
etc. 
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3.1 Simple-Types (and Ordinal-Types) 

All the simple-types define ordered sets of values. 

simple-type 



•^ 



ordinal-type 



""--^ real-type 



* string-type 



real-type ^| yeal-type-ldentifier 



orcflnal-type 






subrange-type 



enumerated- type 



ordinal-type-identifier 



"N 



X4 



The standard real-type-identifier is real. 

String-types are discussed in Section 3.1.1.6 below. 

Onainal-types are a subset of the simple-types, with the following special 
characteristics: 

• Within a given ordinal-type, the possible values are an ordered set and each 
possible value is associated with an orcfinallty, which is an integer value. 
The first value of the ordinal-type has ordinality 0, the next has ordinality 
1, etc. Each possible value except the first has a predecessor based on 
this ordering, and each possible value except the last has a successor based 
on this ordering. 

• The standard function ord (see Section 11.5.1) can be applied to any value 
of ordinal-type, and returns the ordinality of the value. 

• The standard function pred (see Section 11.5.4) can be applied to any value 
of ordinal-type, and returns the predecessor of the value. (For the first 
value in the ordinal-type, the result is unspecified.) 

• The standard function suae (see Section 11.5.3) can be applied to any value 
of ordinal-type, and returns the successor of the value. (For the first value 
in the ordinal-type, the result is unspecified.) 
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All simple-types except real and the string-types are ordinal-types. The 
standard ordinal-type-identifiers are: 

integer 
lon^t 
char 
txMlean 

Note that in addition to these standard types, the enumerated-types and 
subrange-types are ordinal-types. 

3.1.1 Standard Simple-Types and String-Types 

A Standard type is denoted by a predefined type-identifier. The simple-types 
integer, longlnt, real, char, and boolean are standard. The string-types are 
user-defined simple-types. 

3.LL1 The Integer Type 

The values are a subset of the whole numbers. (As constants, these values can 
be denoted as specified in Section 1.4.) The predefined integer constant maxint 
is defined to be 32767. Maxint defines the range of the type integer as the 
set of values: 

-maxint-1, -maxint, ... -1, 0, 1, ... maxint-l, maxint 

These are 16-bit, 2's-complement integers. 

3.1.12 Tlie Longint Type 

The values are a subset of the whole numbers. (As constants, these values can 

be denoted as specified in Section 1.4.) The range Is the set of values from 

-(2^^-l) to 2^^-!, i.e., -2147483648 to 2147483647. 

These are 32-bit integers. 

Arithmetic on integer and longint operands is done in both 16-bit and 32-bit 
precision. An expression with mixed operand sizes is evaluated in a manner 
similar to the FORTRAN single/double precision floating-point arithmetic rules: 

• All "integer" constants in the range of type integer are considered to be of 
type int€^r. All "Integer" constants in the range of type longint, but not 
in the range of type integer, are considered to be of type lon^nt 

• When both operands of an operator (or the single operand of a unary 
operator) are of type integer, 16-bit operations are always performed and 
the result is of type integer (truncated to 16 bits if necessary). 

• When one or both operands are of type longint, all operands are first 
converted to type longint, 32-bit operations are performed, and the result is 
of type longint However, if this value is assigned to a variable of type 
integer, it is truncated (see next rule). 
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• The expression on the right of an assignment statement is evaluated 
independently of the size of tfje varJatfJe m the left If necessary, the 
result of the expression is truncated or extended to match the size of the 
variable on the left 

The onW function (see Section 11.3.3) can be used to convert an Integer value 
to a longint value. 

IMPLEMENTATION NOTE 

There is a performance penalty for the use of longint values. The 
penalty is essentially a factor of 2 for operations other than division 
and multiplication; for division and multiplication, the penalty is much 
worse than a factor of 2. 



3.1.13 The Real Type 

For details of IEEE standard floating-point arithmetic, see Appendix D. The 
possible real values are 

• Finite values (a subset of the mathematical real numbers). As constants, 
these values can be denoted as specified in Section 1.4. 

The largest absolute numeric real value is approximately 3.402823466E38 in 
Pascal notation. 

The smallest absolute numeric non-zero real value is approximately 
1.401298464E-45 in Pascal notation. 

The real zero value has a sign, like other numbers. However, the sign of a 
zero value is disregarded except in division of a finite number by zero and 
in textual output. 

• Infinite values, +«> and -«». These arise either as the result of an operation 
that overflows the maximum absolute finite value, or as the result of 
dividing a finite value by zero. Appendix D gives the rules for arithmetic 
operations using these values. 

• NaNs (the word "NaN" stands for "Not a Number"). These are values of 
type real that convey diagnostic information. For example, the result of 
multiplying «» py is a NaN. 

3.1.1.4 TTie Boolean Type 

The values are truth values denoted by the predefined constant identifiers false 
and true. These values are ordered so that Mse is "less than" true. The 
function-call ordffalse) returns 0, and ord(true) returns 1 (see Section 11.5.1). 

3.1.15 The Char Type 

The values are extended 8-blt ASCII, represented by numeric codes in the 
range 0..255. The ordering of the char values is defined by the ordering of 
these numeric codes. The function-call orcl(cX where c is a char value, returns 
the numeric code of c (see Section 11.5.1). 
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3.1.L6 String-Types 

A string value Is a sequence of cliaracters that has a dynamic length attri- 
bute. The length is the actual number of characters in the sequence at any 
time during program execution. 

A string type has a static size attribute. The size is the maximum limit on 
the length of any value of this type. The current value of the length attribute 
is returned by the standard function length (see Section 11.6); the size attribute 
of a string type is determined when the string type is defined. 

strlng-tjpe 

■» ( string ) — ►(T) — ^ size-attribute — Kj)" 



strlng-type-ldentifier 



J 



sJze-attriUute 



unsigned-integer 



where the size attribute Is an unsigned-integer. 

IMPLEMENTATION NOTE 



In the current Implementation, the size-attribute must be in the range 
from 1 to 255. 



The ordering relationship between any two string values is determined by 
lexical comparison based on the ordering relationship between character values 
in corresponding positions in the two strings. (When the two strings are of 
unequal lengths, each character in the longer string that does not correspond to 
a character in the shorter one compares "higher"; thus the string 'attribute' is 
ordered higher than 'at'.) 



Do not confuse the size with the length. 
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NOTES 

The size attribute of a string constant is equal to the length of the 
string constant value, namely the number of characters actually in the 
string. 

Although string-types are simple-types by definition, they have some 
characteristics of structured-types. As explained in Section 4.3.1, 
individual characters In a string can be accessed as if they were 
components of an array. Also, all string-types are implicitly packed 
types and all restrictions on packed types apply to strings (see Sections 
7.3.2, 5.1.6.1, and 11.7). 

Do not make any assumptions about the internal storage format of strings, as 
this format may not be the same in all implementations. 

Operators applicable to strings are specified in Section 5.1.5. Standard 
procedures and functions for manipulating strings are described in section 11.6. 

3.1^ Enumerated-Types 

An enumerated-type defines an ordered set of values by listing the identifiers 
that denote these values. The ordering of these values is determined by the 
sequence in which the identifiers are listed. 



enumeratea-type ^ (Jy^ identifier-list h»()>-» 



identifier-list 



identifier 



_^ 

^ — O— ^ 

The occurrence of an identifier within the identifier-list of an 
enumerated-type declares it as a constant for the block in which the 
enumerated-type is declared. The type of this constant is the enumerated-type 
being declared. 

Examples of enumerated-types: 

color = (red, yellow, green, blue) 

suit = (club, diamond, heart, spade) 

maritaistatus = (married, divorced, wldoved, single) 

Given these declarations, yellow is a constant of type color, diamond is a 
constant of type suit, and so forth. 

When the ord function (see Section 11.5.1) is applied to a value of an 
enumerated-type, it returns an integer representing the ordering of the value 
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with respect to the other values of the enumerateo-type. For example^ given 
the declarations above, oid[red) returns 0, ord(yellow) returns l, and ord(blue) 
returns 3. 

3.1.3 Subrange-Types 

A subrange-type provides for range-checking of values within some 
ordinal-type. The syntax for a subrange-type is 



"^"^'^-^^^ »l constant 



Both constants must be of ordinal-type. Both constants must either be of the 
same ordinal-type, or one must be of type integer and the other of type 
longint If both are of the same ordinal-type, this type is called the host-type 
If one is of type Integer and the other of type longint the host-type is longint 
Note that no range-checking is done if the host-type is longint 

Examples of subr&ige-types: 

1..100 
-10.. ♦lO 

red.. green 

A variable of subrange-type possesses all the properties of variables of the 
host type, with the restriction that its run-time value must be in the specified 
closed interval. 

IMPLEMENTATION NOTE 

Range-Checking is enabled and disabled by the compiler commands $R+ 
and $R- (see Chapter 12). The default is $R+ (range-checking enabled). 

3.2 structureo-Types 

A Structured-type is characterized by its structuring method and by the type(s) 
of its components, if the component type is Itself structured, the resulting 
structured-type exhibits more than one level of structuring. There Is no 
specified limit on the number of levels to which data-types can be structured. 



stJXAiti/recf-lwe 




^— ^ structured-type-ldentlfier 



_y 
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The use of trie word packed in the declaration of a structured-type indicates 
to the compiler that data storage should be economized, even if this causes an 
access to a component of a variable of this type to be less efficient 

The word packed only affects the representation of one level of the 
structured-type in which it occurs. If a component is itself structured^ the 
component's representation is packed only if the word packed also occurs in 
the declaration of its type. 

For restrictions on the use of components of packed variables, see Sections 
7.3.2, 5.1.6.1, and 11.7. 

The implementation of packing is complex, and details of the allocation of 
storage to components of a packed variable are unspecified 

IMPLEMENTATiast ^4C3rrE 

In the current implementation, the word packed has no effect on types 
other than array and record. 

3.2.1 Array-Types 

An array-type consists of a fixed number of components that are all of one 
type, called the component-type The number of elements is determined by 
one or more Index-types, one for each dimension of the array. There is no 
specified limit on the number of dimensions. In each dimension, the array can 
be indexed by every possible value of the corresponding index-type, so the 
number of elements is the product of the cardinalities of all the Index-types. 

array-type 

—» {array ) -»(?)-?-» index-type — y»(J)--»(or)-» | type [ ^ 



C~\a J 



index-type 



ordinal-type 



The type following the word of is the conponent-type of the array. 

IMPLEMENTATION NCrTE 

In the current implementation, the index-type should not be longint or a 
subrange of longint, and arrays should not contain more than 32767 bytes. 
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Examples of array-types: 

array[1..100] of real 
array[l300lean] of color 

If the component-type of an array-type is also an array-type, the result can be 
regarded as a single multi-dimensional array. The declaration of such an array 
is equivalent to the declaration of a multi-dimensional array, as illustrated by 
the following examples: 

array[l)oolean] of array[l.-10] of array[size] of real 
is equivalent to: 

array [boolean^ 1.. 10, size] of real 
Likewise, 

packed array[l..lO] of packed array[1..8] of boolean 
is equivalent to: 

packed array [1.. 10, 1.. 8] of boolean 

"Equivalent" means that the compiler does the same thing with the two 
constructions. 

A component of an array can be accessed by referencing the array and 
applying one or more indexes (see Section 4.3.1). 

3.22 Record-Types 

A record-type consists of a fixed number of components called fields, possibly 
of different types. For each component, the record-type declaration specifies 
the type of the field and an identifier that denotes it. 



recoid-type ^ (^^^^ 



^ field-list \-^ 



► (end} -» 




fixed-part 



r 



field-declaration 



<I> 



T 
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fleia-aeclawUon 



identifier-list — K^) — *" ^^P® 



The fixed-part of a record-type specifies a list of "fixed" fields, giving an 
identifier and a type for each field. Each of these fields contains data that is 
always accessed in the same way (see section 4.3.2). 

Example of a record- type: 

record 
year: integers- 
month: 1..12; 
day: 1..31 

end 

A variant-part allocates memory space with more than one list of fields, thus 
permitting the data in this space to be accessed in more than one way. Each 
list of fields is called a variant The variants "overlay" each other in memory, 
and all fields of all variants are accessible at all times. 



variant-part 

L C8S6 J 



identifier 




tag-field-type -H^of) 



I r ¥ variant ^d^ 



variant 



-r-¥- constant \ ^^Gy^X) — "s irKj) — *^ 

I r\^ J ^ field-list K 



O 



taj-fJeia-twJe 



ordinal-type-ldenUfier 



IMPLEMENTATION NOTE 



In the current implementation, the type longint should not be used as a 
tag-type as it will not work correctly. 
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Each variant is introduced by one or more constants. All the constants must 
be distinct and must be of an ordinal-type that is compatible with the 
tag-type (see Section 3.4). 

The variant-part allows for an optional identifier, called the tag-field 
identifier. If a tag-field identifier is present, it is automatically declared as 
the identifier of an additional fixed field of the record, called the tag- field 

The value of the tag-field may be used by the program to indicate which 
variant should be used at a given time. If there is no tag-field, then the 
program must select a variant on some other criterion. 

Examples of record-types with variants: 

record 
name, firstNarae: strlng[80]; 
age: 0..99; 

case married: boolean of 
true: (spousesName: string[80]); 
false: 
end 

record 
)Cy: real; 
area: real; 
case s: shape of 
triangle: (side: real; inclination, anglel, angle2: 

angle); 
rectangle: (sidel, side2 : real; skew, angle3: angle); 
circle: (diameter: real); 
end 

NOTE 

The constants that introduce a variant are not used for referring to 
fields of the variant; however, they can be used as optional arguments 
of the new procedure (see Section 11.2). Variant fields are accessed in 
exactly the same way as fixed fields (see Section 4.3.2). 

3.23 Set-Types 

A set-type defines a range of values that is the powerset of some ordinal-type, 
called the Dase-type in other words, each possible value of a set-type is some 
subset of the possible values of the base-type. 



^^~^iP^ — ^^^'^t')--»(oiF)--» | ordinal-type 
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IMPLEMENTATION NOTE 

In the present implementation the base-type must not be longint The 
base-type must not have more than 4088 possible values. If the base- 
type is a subrange of integer^ it must be within the limits 0..a087. 

Operators applicable to sets are specified in Section 5.1.4. Section 5.3 shows 
how set values are denoted in Pascal. 

Sets with less than 32 possible values in the base-type can be held in a 
register and offer the best performance. For sets larger than this, there is a 
performance penalty that is essentially a linear function of the size of the 
base-type. 

The empty set (see Section 5.1.4) is a possible value of every set-type. 

3.2.4 File-Types 

A file-type is a structured-type consisting of a sequence of components that 
are all of one type, the component-typa The component-type may be any 
type. 

The component data is not in program-addressable memory but is accessed via 
a peripheral device. The number of components (i.e. the length of the file) is 
not fixed by the file-type declaration. 



file-type 



<ite> 



of )-W type 



The type file (without the "of type" construct) represents a so-called "untyped 
file" type for use with the blockread and blockwrite functions (see Section 
10.4). 

NOTE 

Although the symbol file can be used as if it were a type-identifier, it 
cannot be redeclared since it is a reserved word. 



The standard file-type text denotes a file of text organized into lines. The 
file may be stored on a file-structured device, or it may be a stream of 
characters from a character device such as the Lisa keyboard. Files of type 
text are supported by the specialized I/O procedures discussed in Section 10.3. 

In Pascal on the Lisa, the type text is distinct from the type file of char 
(unlike standard Pascal). The type file of char is a file whose records are of 
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type char^ containing char values that are not interpreted or converted in any 
way during I/O operations. 

In a stored file of type text or file of -128..127^ the component values are 
packed into bytes on the storage medium. However^ this does not apply to the 
type file of char; the component values of this type are stored in 16-bit words. 

In Pascal on the Lisa, files can be passed to procedures and functions as 
variable parameters, as explained in Section 7.3.2. 

Sections 4.3.3, 10.2, 10.3, and 10.4 discuss methods of accessing file components 
and data. 

3.3 Pointer-Types 

A pointer- type defines an unbounded set of values that point to variables of a 
specified type called the ibase-t}^ 

Pointer values are created by the standard procedure new (see Section 11.2.1), 
by the » operator (see Section 5.1.6), and by the standard procedure pointer 
(see Section 11.3.4). 



pointer-type 



^^ DC 



\\-^ base- type 



pointer-type-identifier 



tjase-type 



type-identifier 



NOTE 



The base-type may be an identifier that has not yet been declared, 
this case, it must be declared somewhere in the same block as the 
pointer-type. 



In 



3.4 



The special symbol nil represents a standard pointer-valued constant that is a 
possible value of every pointer type. Conceptually, nil is a pointer that does 
not point to anything. 

Section 4.3.4 discusses the syntax for referencing the object pointed to by a 
pointer variable. 

Identical and Compatible Types 

As explained below, this Pascal has stronger typing than standard Pascal. In 
Pascal on the Lisa, two types may or may not be identical and identity is 
required in some contexts but not in others. 
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Even if not identical, two types may still be compatibJe, and this is sufficient 
in contexts where identity is not required—except for assignment where 
assignment-compatibility is required. 

3A1 Type Identity 

Identical types are required only in the following contexts: 

• Variable parameters (see Section 7.3.2). 

• Result types of functional parameters (see Section 7.3.4X 

• Value and variable parameters within parameter-lists of procedural or 
functional parameters (see Section 7.3.5). 

• One-dimensional packed arrays of char being compared via a relational 
operator (see Section 5.1.5). 

Two types, H and M, are identical if either of the following is true: 

• The same type identifier is used to declare both tl and 12, as in 

foo = "integer; 
tl = foo; 
t2 = foo; 

• tl is declared to be equivalent to tz as in 

tl = t2; 

Note that the declarations 

tl = t2; 
t3 = tl; 

do not make t3 and t2 identical, even though they make tl identical to t2 and 
t3 Identical to tl! 

Also note that the declarations 

t4 = integer; 
t5 = integer; 

do make t4 and t5 identical, since both are defined by the same type 
identifier. In general, the declarations 

t6 = XI; 
t8 = t7; 

do make t6 and t8 identical if t7 is a type-identifier. 

However, the declarations 

t9 = "integer; 
tio = "integer; 

do not make t9 and tlO identical since "integer is not a type identifier but a 
user-defined type consisting of the special symbol " and a type Identifier. 
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Finally, note tnat two variables declared in the same declaration, as in 

varl„ var2: "intecpr; 

are of identical type. However, if the declarations are separate then the 
definitions above apply. 

The declarations 

varl: "integer; 

v/ar2: "Integer; 

var3: integer; 

var4: integer; 

make var3 and var4 identical in type, but not varl and var2. 

3.4.2 Compatibility of Types 

Compatibility is required in the majority of contexts where two or more 
entities are used together, e.g. in expressions. Specific instances where type 
compatibility is required are noted elsewhere in this manual. 

Two types are conpatible if any of the following are true: 

• They are identical. 

• One is a subrange of the other. 

• Both are subranges of the same type. 

• Both are string-types (the lengths and sizes may differ). 

• Both are set-types, and their base-types are compatible. 

3.4.3 Assignment-Compatibility 

Assignment-compatibility is required whenever a value is assigned to 
something, either explicitly (as in an assignment-statement) or implicitly (as in 
passing value parameters). 

The value of an expression expval of type exptyp is assignment-compatible 
with a variable, parameter, or function-identifier of type vtyp if any of the 
following is true. 

• vtyp and exptyp are identical and neither is a file-type, or a structured- 
type with a file component. 

• vtyp is real and exptyp is integer or longint (expval is coerced to type 
real). 

• vtyp and exptyp are compatible ordinal-types, and expval is within the 
range of possible values of vtyp. 

• vtyp and exptyp are compatible set-types, and all the members of expval 
are within the range of possible values of the base-type of vtyp. 

• vtyp and exptyp are string types, and the current length of expval is equal 
to or less than the size-attribute of vtyp. 
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• vtyp is a string type or a char type and expval is a quoted-character- 
constant. 

• vtyp is a packed aiTay[l../7] of char and expval is a string constant 
containing exactly n characters. 

If the index- type of the packed array of char is not I../?, but the array 
does have exactly n elements, no error will occur. However, tne results 
are unspecified. 

Whenever assignment-compatibility is required and none of the above is true, 
either a compiler error or a run-time error occurs. 

3.5 The Type-Declaration-Part 

Any program, procedure, or function that declares types contains a type- 
declaration-part, as shown in Chapter 2. 

Example of a type-declaration-part 

type count = Integer; 
range = integer; 

color = (red, yellow, green, blue); 
sex = (male, female); 
year = 1900.. 1999; 
shape = (triangle, rectangle, circle); 
card = array [1.. 80] of char; 
str = string[80]; 

polar = record r: real; theta: angle end; 
person = "personOetails; 
personDetails = record 

name, firstName: str; 

age: Integer; 

married: boolean; 

father, child, sibling: person; 

case s: sex of 
male: (enlisted, bearded: boolean); 
female: (pregnant: boolean) 
end; 

people = file of personDetails; 
intf ile = file of integer; 

In the above example count, range, and integer denote identical types. The 
type year is compatible with, but not identical to, the types range, count, and 
integer. 
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^1 Variable-Declarations 

A variable-declaration consists of a list of identifiers denoting new variables, 
followed by their type. 



varl^le-declaraUon 



identifier-list -►(T)-*' type "KT) ► 



4.2 



The occurrence of an identifier within the identifier-list of a variable- 
declaration declares it as a variable-identifier for the block in which the 
declaration occurs. The variable can then be referenced throughout the 
remaining lexical extent of that block, except as specified in Section 2.2.2. 

Examples of variaUe-c/eclarations: 

x,y^z: real; 

tj: integer; 

k: 0..9; 

p,q,r: boolean; 

q:«rator: (plus, minus, times); 

a: array[0..63] of real; 

c: color; 

f : file of char; 

huel,hue2: set of color; 

pl,p2: person; 

Buml,m2: array[l..lO,1..10] of real; 

coord: polar; 

pooltape: array[1..4] of tape; 

Variable-References 

A variable-reference denotes the value of a variable of simple-type or 
pointer-type, or the collection of values represented by a variable of 
structured-type. 

variable-refei^nce 

► 



variable-identifier 



X\ 



qualifier 



^ 



variable-identifier 



identifier 
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Syntax for the various kinds of qualifiers is given below. 

4.3 Qualifien 

As Shown above, a variable-reference is a variable-identifier followed by zero 
or more qualifiers. Each qualifier modifies the meaning of the variable- 
reference. 



Qualifier 



^ 



^-^ 



index 



field-designator 



file-buffer-symbol 



^ pointer-object-symbol 



^ 



An array identifier with no qualifier is a reference to the entire array: 

xResults 

If the array identifier is followed by an index., this denotes a specific 
component of the array: 

xResults [ current +1 ] 

If the array component is a record, the index may be followed by a field- 
designator; in this case the variable-reference denotes a specific field within a 
specific array component. 

xResults[current+l] .link 

If the field is a pointer, the field-designator may be followed by the pointer- 
object-symbol, to denote the object pointed to by the pointer: 

XResults [current+l] . link " 

If the object of the pointer Is an array, another index can be added to denote 
a component of this array (and so forth): 

xResults[current+l] . link " [1] 

4.3.1 Arrays, strings, and Indexes 

A specific component of an array variable is denoted by a variable-reference 
that refers to the array variable, followed by an index that specifies the 
component. 

A specific character within a string variable is denoted by a variable-reference 
that refers to the string variable, followed by an index that specifies the 
character position. 



irxiex 



<L> 



I 



expression 



I 
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Exanples of indexed arrays: 

m[i.J] 
a[l-J] 

Each expression in the index selects a component in the corresponding 
dimension of the array. The number of expressions must not exceed the 
number of index-types in the array declaration, and the type of each 
expression must be assignment-compatible with the corresponding index-type. 

In indexing a multi-dimensional array, you can use either multiple indexes or 
multiple expressions within an index. The two forms are completely equivalent 
For example, 

m[i][j] 

is equivalent to 

in[i,j] 

For array variables, each index expression must be assignment-compatible with 
the corresponding index-type specified in the declaration of the array-type. 

A string value can be indexed by only one index expression, whose value must 
be in the range I../7, where n is the current length of the string value. The 
effect is to access one character of the string value. 

WARNING 

When a string value is manipulated by assigning values to individual 
character positions, the dynamic length of the string is not maintained. 
For example, suppose that strval is declared as follows: 

strval: string[lO]; 

The memory space allocated for strval includes space for 10 char values 
and a number that will represent the current length of the string— i.e., 
the number of char values currently in the string. Initially, all of this 
space contains unspecified values. The assignment 

strval[l]:='F* 

may or may not work, depending on what the unspecified length happens 
to be. If this assignment works, it stores the char value *F' in character 
position 1, but the length of strval remains unspecified. In other words, 
the value of stival[l] is now "F', but the value of strval is unspecified. 
Therefore, the effect of a statement such as writeln(strval) is 
unspecified. 

Therefore, this kind of string manipulation is not recommended. Instead, 
use the standard procedures described in Section 11.6. These procedures 
properly maintain the lengths of the string values they modify. 



4-3 



Pascal Reference Manual Varisi)les 



4.3.2 Records and Field-Designatx>n 

A specific field of a record variable is denoted by a variable-reference that 
refers to the record variable^ followed by a field-designator that specifies the 
field. 



field-designator 



O 



identifier 



Examples of fieia-designators: 

p2". pregnant 
coord. theta 

/k3.3 Flle-Buffen 

Although a file variable may have any number of components, only one 
component is accessible at any time. The position of the current component in 
the file is called the current file position See Sections 10.2 and 10.3 for 
standard procedures that move the current file position. Program access to the 
current component is via a special variable associated with the file, called a 
file-buffer 

The file-buffer is implicitly declared when the file variable is declared. If F 
is a file variable with components of type T, the associated file-buffer is a 
variable of type T. 

The file-buffer associated with a file variable is denoted by a variable- 
reference that refers to the file variable, followed by a qualifier called the 
file-buffer-symbol. 



file-lMjffer-smttol 



O 



Thus the file-buffer of file F is referenced by F*. 

Sections 10.2 and 10.3 describe standard procedures that are used to move the 
current file position within the file and to transfer data between the file- 
buffer and the current file component. 

4.3.4 Pointers and Their Objects 

The value of a pointer variable is either nil, or a value that identifies some 
other variable, called the obpct of the pointer 

The object pointed to by a pointer variable is denoted by a variable-reference 
that refers to the pointer variable, followed by a qualifier called the pointer- 
object-symbol. 



pointer-obfect-symnol 



O 
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NOTE 

Pointer values are created by the standard procedure new (see Section 
11.2.1X by the e operator (see Section 5.1.6), and by the standard 
procedure pointer (see Section 11.3.4). 

The constant nil (see Section 3.3) does not point to a variable. If you access 
memory via a nil pointer reference, the results are unspecified; there may not 
be any error indication. 

Exmiples of references to objects of pointers: 
pi .sibling 
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Expressions consist of operators and operands, i.e. variables, constants, set- 
constructon, and function calls. Table 5-1 shows the operator precedence: 

Table 5-1 
Precedence of Qperator; 



Cperatars 


Prec&ience 


Categories 


•, not 


highest 


unary operators 


\ 1. cliv, 
mod, and 


second 


"multiplying" operators 


♦, -, or 


third 


"adding" operators & signs 


<», >=, in 


lowest 


relational operators 



The following rules specify the way in which operands are bound to operators: 

• When an operand is written between two operators of different precedence, 
it is bound to the operator with the higher precedence. 

• When an operand is written between two operators of the same precedence, 
it is bound to the operator on the left. 

Note that the order in which operations are performed is not specified. 

These rules are implicit in the syntax for expressions, which are built up from 
factors, terms, and simple-expressions. 

The syntax for a /actor allows the unary operators m and not to be applied to 
a value: 



factor 



"^ 



^^ 



^ variable-reference 



^ 



unsigned-constant 



function-call 



set-constructor 
\C)~~^ expression 
Kjnot)-» factor - 



Ki> 



"^ 



■^ 
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A function-call activates a function, and denotes the value returned by the 
function (see Section 5.2). A set-constructor ^Hs^XiX^i a value of a set-type (see 
Section 5.3). An unsigned-constant has the following syntax: 



unsigned-constant 






^ 



unsigned-number 



quoted-strlng-constant 



constant-identifier 



-Kh> 



Examples of f acton: 

X 

ax 

15 

(x+y+z) 

sin(x/2) 

[•A'..'F".'a'.."f ] 

not p 

The syntax for a term allows the "multiplying" operators to be applied to 
factors: 



{variable-reference} 

{pointer to a variable} 

{unsigned-constant} 

{sub-expression} 

{function-call} 

{set-constructor} 

{negation of a boolean} 




( ^ wi£y ^ — 



Examples of terms: 

x*y 

i/(l-i) 

p and q 

(x <= y) and (y < z) 
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The syntax for a simple-e^pressim allows the "adding" operators and signs to 
be applied to terms: 



simple-expressJon 



V I — ,/ 

^"^ sian -^ 



term 



■^ 



^ 






Ex&T/ples of sIfrple-e>pressIons: 

x+y 

-X 

huel * hue2 

i*J ♦ 1 

The syntax for an e)q}ression allows the relational operators to be applied to 
simple-expressions: 



egression 



simple-expression 




simple-expression 



Examples of egressions: 

X = 1.5 
p <= q 

p = q and r 

(i < J) = (J < k) 
c in huel 
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5.1 Opeiaton 

5.1.1 Binary Operators: Order of Evaluation of Operands 

The order of evaluation of the operands of a binary operator is unspecified. 

5.1.2 Arithmetic qperaton 

The types of operands and results for arithmetic binary and unary operations 
are shown in Tables 5-2 and 5-3 respectively. 

Tdble 5-2 
Binary Arithmetic Operations 



qotemtor 


Cperation 


Cperand Types 


Type of Result 


* 


addition 


integer^ real^ or 
longint 


integer, real, or 
longint 


- 


siiJtra^tion 


» 


multiplication 


/ 


division 


integer, real, or 
longint 


real 


div 


division with 
integer result 


integer or longint 


integer or longint 


mud 


modulo 


integer or longint 


integer 


Note: The symbols *^ -^ and * are also used as set operators (see 
Section 5.1.ftX 



Table 5-3 
unary Arithmetic Operations (Signs) 



cperator 


cperation 


operana Types 


Type of Result 


♦ 


identity 


integer, real, or 
longint 


same as operand 


- 


sign-negation 



Any operand whose type is subr, where subr is a subrange of some ordinal-type 
ordtyp, is treated as if it were of type ordtyp. Consequently an expression 
that consists of a single operand of type subr is itself of type ordtyp. 
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If both the operands of the addition^ subtraction^ or multiplication operators 
are of type Integer or longint^ the result Is of type integer or longint as 
described in Section 3.1.1.2; otherwise^ the result is of type real 

NOTE 

See Appendix D for more information on all arithmetic operations with 
operands or results of type real. 

The result of the identity or sign-negation operator is of the same type as the 
operand. 

The value of i div j is the mathematical quotient of i/j, rounded toward zero 
to an integer or longint value. An error occurs if j-0. 

The value of I mod j is equal to the value of 

i - (i div j)*j 

The sign of the result of mod is always the same as the sign of 1. An error 
occurs if j-0. 

The predefined constant maxlnt is of type integer. Its value is 32767. This 
value satisfies the following conditions: 

• All whole numbers in the closed interval from -maxint-1 to +maxlnt are 
representable in the type integer. 

• Any unary operation performed on a whole number in this interval will be 
correctly performed according to the mathematical rules for whole-number 
arithmetic. 

• Any binary integer operation on two whole numbers in this same interval 
will be correctly performed according to the mathematical rules for 
whole-number arithmetic, provided that the result is also in this interval. 
If the mathematical result is not in this interval, then the actual result is 
the low-order 16 bits of the mathematical result. 

• Any relational operation on two whole numbers in this same interval will be 
correctly performed according to the mathematical rules for whole-number 
arithmetic. 
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5.1.3 Boolean Operators 

The types of operands and results for Boolean operations are shown In Table 
5-4. 

Table 5-4 
Boolean Operations 



Operator 


Operation 


cperancf Types 


Type of Result 


or 


disjunction 


tx»lean 


txjolean 


and 


conjunction 


not 


negation 



Whether a Boolean expression is completely or partially evaluated if its value 
can be determined by partial evaluation is unspecified. For example, consider 
the expression 

true or doolTst(x) 

where boolTst is a function that returns a boolean value. This expression will 
always have the value true, regardless of the result of boolTst(x)i The language 
definition does not specify whether the boolTst function is called when this 
expression is evaluated. This could be important if boolTst has side-effects. 

5.1.4 SetOperaton 

The types of operands and results for set operations are shown in Table 5-5. 



Table 5-5 
Set Operations 



Operator 


Operation 


Cperand Types 


Type of Result 


♦ 


union 


connpatlble 
set-types 


(see 5.1.4.1) 


- 


difference 


m 


intersection 
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5.1A1 Result Type In Set Gpeiations 

The following rules govern the type of the result of a set operation where one 
(or both) of the operands is a set of subr, where ordtyp represents any 
ordinal-type and subr represents a subrange of ordtyp: 

• If ordtyp is not the type Integer^ then the type of the result is set of 
ordtyp. 

• If ordtyp is the type integer^ then the type of the result is set of [L4D87 in 

the current implementation (0..32767 in a future implementation). This rule 
results from the limitations on set-types (see Section 3.2.3). 

5.15 Relational Operaton 

The types of operands and results for relational operations are shown in Table 
5-6^ and discussed further below. 

Table 5-6 
Relational Gpeiations 



Operator 


Cperation 


Operand Types 


Type of Result 


- 


equal 


compatible set-, 
sinple-, or 
pointer-types 
(& see below) 


boolean 


<> 


not equal 


< 


less 


compatible 
simple-types 
(& see below) 


> 


greater 


<» 


less/equal 


>» 


greater/equal 


<= 


subset of 


compatible 
set-types 


>- 


superset of 


in 


member of 


left opermck 

any ordinal-type T 

set of T 



5.1.5.1 Comparing Numbers 

When the operands of <, >, >-, or <- are numeric, they need not be of 
compatible type // one operand is real and the other is integer or longinL 

NOTE 

See Appendix D for more information on relational operations with 
operands of type real. 
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5.15.2 Comparing Booleans 

If p and q are txwlean operands, then p-q denotes their equivalence and p<-q 
denotes the implication of q by p (because false<true). Similarly, p<>q denotes 
logical "exclusive-or." 

5.1.5.3 Comparing Strings 

When the relational operators -,<>,<,>,<-, and > are used to compare 
strings (see Section 3.1.1.6), they denote lexicographic ordering according to the 
ordering of the ASCII character set. Note that any two string values can be 
compared since all string values are compatible. 

5.1.5.4 Comparing Sets 

If u and V are set operands, then u<-v denotes the inclusion of u in v, and 
u>-v denotes the inclusion of v in a 

5.13.5 TesUng Set Membership 

The in operator yields the value true if the value of the ordinal-type operand 
is a member of the set-type operand; otherwise it yields the value false. 

5.1.5.6 Comparing Packed Arrays of Char 

In addition to the operand types shown in the table, the - and <> operators can 
also be used to compare a packed anay[lJsl] of char with a string constant 
containing exactly N characters, or to compare two one-dimensional packed 
arrays of char of identical type. 

5.1.6 »-qperator 

A pointer to a variable can be connputed with the ©-operator. The operand 
and result types are shown in Table 5-7. 



Table 5-7 
Pointer Operation 



Operator 


Operation 


Operand 


Type of Result 


m 


pointer 
foin ration 


variable, parameter, 
procedure, or 
function 


sane as nil 



» is a unary operator taking a single variable, parameter, procedure, or 
function as its operand and computing the value of its pointer. The type of 
the value is equivalent to the type of nil, and consequently can be assigned to 
any pointer variable. 



5-8 



Pascal Reference Manual Expressions 

5.1^1 9-operator With a variable 

For an ordinary variable (not a pargfineter), the use of » is straightforward. For 
example, if we have the declarations 

type tiwchar = packed array [0..1] of char; 
var int: integer; 

twocharptr: "twochar; 

then the statement 

tDOcharptr := aint 

causes twocharptr to point to inL Now twocharptr" is a reinterpretation of 
the bit value of int as though it were a packed array[a.l] of char. 

The operand of © cannot be a component of a packed variable. 

5.1^^ ©-Operator With a Value Parameter 

When • is applied to a formal value parameter, the result is a pointer to the 
stack location containing the actual value. Suppose that foo is a formal value 
parameter in a procedure and fooptr is a pointer variable. If the procedure 
executes the statement 

fooptr := afOG 

then fooptr" is a reference to the value of foa Note that if the actual- 
parameter is a variable-reference, fooptr" is not a reference to the variable 
itself; it is a reference to the value taken from the variable and stored on the 
stack. 

5.1.6.3 ©-Operator With a Variable Parameter 

When © Is applied to a formal variable parameter, the result is a pointer to 
the actual-parameter (the pointer is taken from the stack). Suppose that fum 
is a formal variable parameter of a procedure, fie is a variable passed to the 
procedure as the actual-parameter for fum, and ftimptr is a pointer variable. 

If the procedure executes the statement 

fumptr := afum 

then fumptr is a pointer to He. fumptr" is a reference to fie Itself. 

5.1.6.4 fiKJperator With a Procedure or Function 

It is possible to apply © to a procedure or a function, yielding a pointer to the 
entry-point Note that Pascal provides no mechanism for using such a pointer. 
Currently the only use for a procedure pointer is to pass it to an assembly- 
language routine, which can then JSR to that address. 

If the procedure pointed to is in the local segment, © returns the current 
address of the procedure's entry point If the procedure is in some other 
segment, however, © returns the address of the jump table entry for the 
procedure. 
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In logical memory mapping (see Workshop User's Guide for the Lisa), tne 
procedure pointer is always valid. 

In physical memory mapping, code swapping may change a local-segment 
procedure address without warning, and the procedure pointer can become 
invalid. If the procedure is not in the local segment, the jump-talDle entry 
address will remain valid despite swapping because the jump table is not 
moved. 

5.2 Function-Calls 

A function-call specifies the activation of the function denoted by the 
function-identifier. If the corresponding function-declaration contains a list of 
formal-parameters, then the function-call must contain a corresponding list of 
actual-parameters. Each actual-parameter is substituted for the corresponding 
formal-parameter. The correspondence is established by the positions of the 
parameters in the lists of actual and formal parameters respectively. The 
number of actual-parameters must be equal to the number of formal 
parameters. 

The order of evaluation and binding of the actual-parameters is unspecified. 



nsicUofi-cdlJ 

► 



function-identifier 



T^i 



actual-parameter-list 



acUjai-parameter-Jist ^ ^ ^ actual-parameter ] ^ » ( )} 



I 



O 






actual-parameter 



_ 



expression 



variable-reference 



procedure-identifier 



^ function-identifier 



^ 



~> 



A function-identifier is any identifier that has been declared to denote a 
function. 



5-10 



Pascal Reference Manual Expressions 

Exanples of funcUm-calls: 

siRn(^65) 
c|ccl(147.k) 
sin(x+y) 
eof(f)^ 
ord(f ) 

5.3 Set-Constructors 

A set-constructor denotes a value of a set-type, and is formed by writing 
expressions within [brackets]. Each expression denotes a value of the set 



set-constructor 



M 



(\>-\ — r^(^ 



>- — - fc momhoT— nrni m — — '' 



^ (> ^ 



ment^r-arom) 



expression 



W{^T}-» expression -^ 



The notation [ ] denotes the empty set, which belongs to every set-type. Any 
member-group x.y denotes as set members the range of all values of the base- 
type In the closed interval x to y. 

If X is greater than y, then x..y denotes no members and [x..y] denotes the 
empty set 

All values designated in member-groups in a particular set-constructor must be 
of the same ordinal-type. This ordinal-type is the base-type of the resulting 
set If an integer value designated as a set member is outside the limits given 
in Section 3.2.3 (0..4087 in the current implementation), the results are 
unspecified. 

Exanrples of set-constructors: 

[red, c, green] 

[1, 5, 10. .k mod 12, 23] 

['A'..'Z*, 'a'.-'z", chr(xcode)] 
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statements denote algorithmic actions^ and are executable. They can be 
prefixed by labels; a labeled statement can be referenced by a goto-statement. 

statenwnt 



^ label \ -*{iy^ "^ 



simple-statement 



^ structured-stalement 



J 



J 



JadeJ 



¥■ digit-sequence 



A digit-sequence used as a label must be in the range 0..9999, and must first 
be declared as described in Section 2.1. 

6.1 Simple Statements 

A simple-statement is a statement that does not contain any other statement 



simple-statement 



T 



assignment-statement 



^ 



procedure-statement 



"^ 



goto-statement 



V 



6.1.1 Assignment-Statements 

The syntax for an assignment-statement is as follows: 



asslgTment-statement 



t:^ 



varistile-reference 



function-identifier 



(j^) — » expression 



The assignment-statement can be used in two ways: 

• To replace the cunent value of a variable by a 
expression 

• To specify an expression whose value is to be returned by a functioa 



To replace the cunent value of a variable by a new value specified as an 
expression 
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The expression must de assignnnent-compatible with the type of the variat)le or 
the result-type of the function. 

NOTTE 

If the selection of the variable involves indexing an array or taking the 
object of a pointer, it is not specified whether these actions precede or 
follow the evaluation of the expression. 

Examples of assignment-statements: 

X := y+z; 

p := (l<=i) and (i<l00); 
i := sqr(k) - (l*j); 
huel := [blue,succ(c)]; 

6.1.2 Procedure-Statements 

A procedure-Statement serves to execute the procedure denoted by the 
procedure-identifier. 

pmceit/ie-statement 

' ► 



procedure-identifier 



^ actual-parameter-list -^ 



(A procedure-identifier is simply an identifier that has been used to declare a 
procedure.) 

If the procedure has formal-parameters (see Section 7.3), the procedure- 
statement must contain a list of actual-parameters that are bound to the 
corresponding formal-parameters. The number of actual-parameters must be 
equal to the number of formal parameters. The correspondence is established 
by the positions of the parameters in the lists of actual and formal parameters 
respectively. 

The rules for an actual-parameter fiP depend on the corresponding formal- 
parameter FP: 

• If FP is a value parameter, AP must be an expression. The type of the 
value of AP must be assignment-compatible with the type of FP. 

• If FP is a variable parameter, AP must be a variable-reference. The type 
of AP must be identical to the type of FP. 

• If FP is a procedural parameter, AP must be a procedure-identifier. The 
type of each formal-paranr^ter of AP must be identical to the type of the 
corresponding formal-parameter of FP. 
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• If FP is a functional parameter, AP must be a function-identifier. The type 
of each formal-parameter of AP must be identical to the type of the 
corresponding formal-parameter of FP, and the result-type of AP must be 
identical to the result-type of PP. 

fMOTE 

The order of evaluation and binding of the actual parameters is 
unspecified. 

Examples of procedure-statements: 

printheadlng; 
transpose(a,n,m); 
bisect (fct^ -1 . 0, +1 . 0, x); 

6.1.3 Goto-Statements 

A goto-statement causes a jump to another statement in the program, namely 
the statement prefixed by the label that is referenced in the goto-statement. 



Qotg-statm^n 



■» (goto} — ► label 



NOTE 



The constants that Introduce cases within a case-statement (see Section 
6.2.2.2) are not labels, and cannot be referenced in goto-statements. 



The following restrictions apply to goto-statements: 

• The effect of a jump into a structured statement from outside of the 
structured statement is unspecified. 

• The effect of a jump between the then part and the else part of an If- 
statement is unspecified. 

• The effect of a jump between two different cases within a case-statement 
is unspecified. 
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b2. Structuret^-Statements 

Structured-statements are constructs composed of other statements that must 
be executed either conditionally (conditional-statements)^ repeatedly 
(repetitive-statements), or in sequence (compound-statement or with-statement). 



structured-statement 



^ 



"•-^ conditional-statement 



compound-statement 



^ 



repetitive-statement 



^ with-statement 



6^.1 Compound-Statements 

The compound-statement specifies that its component statements are to be 
executed in the same sequence as they are written. 



compound-statement 
» (^ begin ^ 



r 



statement 



<I> 



7 



^ (end) - 



Example of compound-statement 

begin 

Z := X; 

X := y; 

y := z 
end 

An important use of the compound-statement is to group more than one 
statement into a single statement in contexts where Pascal syntax only allows 
one statement The symbols begin and end act as "statement brackets." 
Examples of this will be seen in Section 6.2.3.2. 

6.2.2 Conditional-Statements 

A conditional-statement selects for execution a single one (or none) of its 
component statements. 



a^jdJtlcvial-statenwnt 



u 



if-statement 



case-statement 
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62.2.1 if-statements 

The syntax for if-statements is as follows: 



if-statement 



\^y-^ expression 



W (then 



D 



iH 



statement 



^► (elsej — *^ statement -^ 



The expression must yield a result of type txwlean. If the expression yields 
the value true, the statement following the then is executed. 

If the expression yields false and the else part is present, the statement 
following the else is executed; if the else part is not present, nothing is 
executed. 

The syntactic ambiguity arising from the construct: 

If ei then 
if e2 then si 
else s2 

is resolved by interpreting the construct as being equivalent to: 

if el then begin 
if e2 then si 
else s2 
end 

Examples of if-statements: 

if x < 1.5 then z := x+y else z := 1.5; 
if pi o nil then pi := pi" .father; 

6.2.2.2 Case-Statements 

The case-statement contains an expression (the selectol\ and a list of 
statements. Each statement must be prefixed with one or more constants 
(called case-constant^, or with the reserved word otherwise. All the case- 
constants must be distinct and must be of an ordinal-type that Is compatible 
with the type of the selector. 



case-statmwft 



(^case)— » expression 



-K5K 




Otherwise-clause 



KaTd)-» 
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case 



I 



constant 



<2> 



J 



(T)-* statement 



ott^iwjse-c}mjs:e 



-»(7)-» CotlTeivise ) -» statement 



The case-statement specifies execution of the statement prefixed by a case- 
constant equal to the current value of the selector. If no such case-constant 
exists and an otherwise part is present^ the statement following the word 
otherwise is executed; If no otherwise part is present, nothing is executed. 

Exarrples of case-statermnts: 



case operator 


of 


plus: x := 


x+y; 


minus: x := 


x-y; 


times: X := 


x*«y 


end 




case 1 of 




1: X 


:= sln(x); 


2: X 


:= cos(x); 


3,4,5: X 


:= exp(x); 


otherwise x 


:= ln(x) 


end 





IMPLEMENTATION NOTTE 



In the current implementation, the case-statement will not work 
correctly if any case-constant is of type longint or the value of the 
selector is of type longlnt 



6.2.3 Repetitive-Statements 

Repetitive-statements specify that certain statements are to he executed 
repeatedly. 



repetltiue-statement 



-\ 



^ 



repeat- statement - 



while-statement 



^ for-statement 



"> 
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6^.3.1 Repeat-Statements 

A repeat-Statement contains an expression wnich controls the repeated 
execution of a sequence of statements contained within the repeat-statement 



repeat-statement 



-»(^ repeat 



^ 



statement 



O 



J 



-»(until) — ► expression 



The expression must yield a result of type Dooiean. The statements between 
the symbols repeat and until are repeatedly executed until the expression 
yields the value true on completion of the sequence of statements. The 
sequence of statements is executed at least once, because the expression is 
evaluated after execution of the sequence. 

Exanrples of ref^at-stat&rwnts: 

repeat 

k := 1 mod J; 

1 := j; 

J :=k 
until j = 



repeat 

process(f ' 

get(f) 
until eof(f ) 



); 



6.23^ While-Statements 

A While-Statement contains an expression which controls the repeated 
execution of one statement (possibly a compound-statement) contained within 
the While-statement. 



while-statement 



■>(^ while) — ► e>9ression 



The expression must yield a result of type booleaa It is evaluated tjefore 
contained statement is executed. The contained statement is repeatedly 
executed as long as the expression yields the value true. If the expression 
yields false at the beginning, the statement is not executed. 



the 
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The while-statement- 
while b do body 

is equivalent to: 

if b then repeat 

body 
until not b 

Ex&rples of wnile-statements: 

while a[i] <> x do i := i+l 

while i>0 do begin 

if odd(i) then z := z*3C 

i := i div 2; 

X := sqr(x) 
end 

while not eof (f ) do begin 

process(f " ); 

get(f) 
end 

6^33 For-Statements 

The for-statement causes one contained statement (possibly a compound- 
statement) to be repeatedly executed while a progression of values is assigned 
to a variable called the contwl-van'adle 



for-statmiefit 

»(f0r)-» control-variable -♦\^/-** initial-value 



c 



D 



<5) 



^'-^ (downto) -^ 



final-value -»(do)-» statement 



cmtrol-i/arJatile 



^ variable-Identifier 



initial-value 



e)qDression 



final-value 



expression 
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The control-variable must be a variable-identifier (without any qualifier). It 
must be local to the innermost block containing the for-statement, and must 
not be a variable parameter of that block. The control-variable must be of 
ordinal-type, and the initial and final values must be of a type compatible with 
this type. 

The first value assigned to the control-variable is the initial-value. 

If the for-statement is constructed with the reserved word to, each successive 
value of the control-variable is the successor (see Section 3.1) of the previous 
value, using the inherent ordering of values according to the type of the 
control-variable. When each value is assigned to the control-variable, it is 
compared to the final-value; if it is less than or equal to the final value, the 
contained statement is then executed. 

If the for-statement is constructed with the reserved word downto, each 
successive value of the control-variable is the predecessor (see section 3.1) of 
the previous value. When each value is assigned to the control-variable, it is 
compared to the final-value; if it is greater than or equal to the final value, 
the contained statement is then executed. 

If the value of the control-variable is altered by execution of the repeated 
statement, the effect is unspecified. After a for-statement is executed, the 
value of the control-variable is unspecified, unless the for-statement was 
exited by a goto. Apart from these restrictions, the for-statement: 

for V := el to e2 do body 

is equivalent to: 

begin 
tempi := el; 
tenp2 := e2; 

if tempi <= teinp2 then begin 
V := tenpl; 
body; 

while V o tempZ do begin 
V := succ(v); 
body 
end 
end 
end 
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and the for-statement: 

for V := el downto e2 do body 

Is equivalent to: 

begin 
tempi := el; 
teiip2 := e2; 

If teirpl >= tewpZ then begin 
V := tempi; 
body; 

iihile V <> temp2 do begin 
V := pred(v); 
body 
end 
end 
end 

where tempi and temp2 are auxiliary variables of the host type of the variable 
V that do not occur elsewhere in the program. 

Examples of for-statements: 

for i := 2 to 63 do if a[i] > max then max := a[i] 

for i := 1 to n do for j := 1 to n do 
begin 

X := 0; 

for k := 1 to n do X := X + inl[i^k]«ffle[k, j]; 

in[t j] := X 
end 

for := red to blue do q(c) 

6.2.4 Wlth-Statements 

The syntax for a with-statement is 

with-statemEftt 

•—»(^wlthY^ record-variable-reference -y-»(do)--» statement 



i)y-» record-variable-reference -yi*- 

V r\^ ) 



O 



(A record-variable-reference is simply a reference to some record variable.) 
The occurrence of a record-variable-reference in a with-statement affects the 
way the compiler processes variable-references within the statement following 
the word da Fields of the record-variable can be referenced by their field- 
identifiers, without explicit reference to the record-variable. 
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Example of with-statement- 

•ith date do if month = 12 then begin 

month := 1; 

year := year + 1 
end 
else month := month + 1 

This Is equivalent to: 

if date. month = 12 then begin 

date. month := 1; 

date.year := date. year + i 
end 
else date. month := date.month + 1 

Within a with-statement, each variable-reference is checked to see if it can 
be interpreted as a field of the record. Suppose that we have the following 
declarations: 

type recTyp = record 

foo: integers- 
bar: real 
end; 

var baz: recTyp; 
foo: integer; 

The identifier foo can refer both to a field of the record variable baz and to a 
variable of type integer. Now consider the statement 

with baz do begin 
foo := 36; {which foo is this?} 

end 

The foo in this with-statement is a reference to the field baz.foo, not the 
variable foa 

The statement: 

with vl, v2s . . . vn do s 

is equivalent to the following "nested" with-statements: 

with vl do 
with v2 do 

with vn do s 
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If vn in the above statements is a field of both vl and v2^ it is interpreted to 
mean v2.va not vl.va The list of record-variable-references in the with- 
statement is checked from right to left 

If the selection of a variable In the record-variable-list involves the indexing 
of an array or the de-referencing of a pointer^ these actions are executed 
before the component statement is executed. 

WARNttNG 

If a variable in the record-variable-list is a pointer-reference, the value 
of the pointer must not be altered within the with-statement. If the 
value of the pointer is altered, the results are unspecified. 

Example of unsafe with-statement using pointer-reference: 

with ppp" do begin 

ne»»(ppp); {Don't do this ...} 

ppp:=xxx; {... or this} 

end 
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7.1 Procedure-Declarations 

A procedure-declaration associates an identifier with part of a program so that 
it can be activated by a procedure-statement. 

pwcedure-cfeclaration 

procedure-heading -^KT)^ procedure-body "*KT)— ^ 



piacedum-docfy 



\^ 



block 



-»( ^ forward) — >^ 
-» (^extern€fl) -- 



The procedure-heading specifies the identifier for the procedure, and the 
formal parameters (if any). 



pjnceitj!ie-t)eacilr^ 

< procedure }- ^ IdenUfier 



^ 



formal-parameter-list 



VT 



The syntax for a formal-parameter-list is given in Section 7.3. 

A procedure is activated by a procedure-statement (see Section 6.1.2), which 
gives the procedure's identifier and any actual-parameters required by the 
procedure. The statements to be executed upon activation of the procedure 
are specified by the statement-part of the procedure's block. If the 
procedure's identifier is used in a procedure-statement within the procedure's 
block, the procedure is executed recursively. 
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Example of a pwcedure-cfecJaration: 

procedure readlnteger (var f : text; var x: integer); 
var value^dlgitValue: integer; 
begin 
•hile (f * = • ') and not eof(f) do get(f); 
value := 0; 

ihile (f" in ['C./a']) and not eof(f) do begin 
digitvalue := ord(f ) - ord('0*); 
value := 10*value + digitValue; 
get(f) 
end; 

X :s value 
end; 

A procedure-declaration that has forward instead of a block is called a 
forward declaration Somewhere after the forward declaration (and in the 
same block), the procedure is actually defined by a defining declaration-d^ 
procedure-declaration that uses the same procedure-identifier, omits the 
formal-parameter-list, and includes a block. The forward declaration and the 
defining declaration must be local to the same block, but need not be 
contiguous; that is, other procedures or functions can be declared between 
them and can call the procedure that has been declared forward. This permits 
mutual recursion. 

The forward declaration and the defining declaration constitute a complete 
declaration of the procedure. The procedure is considered to be declared at 
the place of the forward declaration. 

Example of forward declaration- 

procedure i»alter(iitn: integer); {forward declaration} 
forward; 

procedure clara(x, y: real); 
begin 

«faiter(4, 5); {OK because waiter is forward declared} 



end; 

procedure waiter; {defining declaration} 
begin 

clara(8.3^ 2.4); 

end; 

A procedure-declaration that has external instead of a block defines the Pascal 
interface to a separately assembled or compiled routine (a PROC in the case 
of assembly language). The external code must be linked with the compiled 
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Pascal host program before execution; see the workshop user's Guide for the 
Lisa for details. 

Exanple of an external pnxjeOjre-declaration: 

procedure makescreenC index: Integer); 
external; 

This means that makescreen is an external procedure that will be linked to the 
host program before execution. 

IMPLEMENTATION NOTTE 

It is the programmer's responsibility to ensure that the external 
procedure is compatible with the external declaration in the Pascal 
program; the current linker does no checking. 



NOTE 

This Pascal (unlike Apple II and Apple III Pascal) does not allow a 
variable parameter of an external procedure or function to be declared 
without a type. To obtain a similar effect^ use a formal-parameter of 
pointer-type^ as In the following example: 

type bigpaoc = packed array[0. .32767] of char; 
bigpaocptr = ''blgpaoc; 

procedure vhatever (bytearray: bigpaocptr); 
external; 

The actual-parameter can be any pointer value obtained via the »- 
operator (see Section 5.1.6). For example. If dots Is a packed array of 
boolean^ It can be passed to whatever by writing 
ifhatever(adots) 



This description of external procedures also spiles to external functions. 
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72. Function-Declarations 

A function-declaration serves to define a part of the program that computes 
and returns a value of simple-type or pointer-type. 

function-declaration 

function-heading -»(7)^ function-body -»(7) — ^ 



function-Oocly 



"X 



V. 



block 



-»{ ^foivard 
-»( ^ externa l^ 



L- 



The function-heading specifies the identifier for the functioa the formal 
parameters (if any), and the type of the function result. 



M]£mil±eMna__j^J^^^y^^^^^^ 



c 



D 



foimal -parameter-list 



— f-^X^y-^ result-type 



result-type 



^ 



ordlnai-type-identlfier 



V. 



real-type-identifier 



~> 



pointer-type-identifier 



\_ 



The syntax for a formal-parameter-list is given in Section 7.3. 

A function is activated by the evaluation of a function-call (see Section 5.2), 
which gives the function's identifier and any actual-parameters required by the 
function. The function-call appears as an operand in an expression. The 
expression is evaluated by executing the function, and replacing the function- 
call with the value returned by the function. 

The statements to be executed upon activation of the function are specified by 
the statement-part of the function's block. This block should normally contain 
at least one assignment-statement (see Section 6.1.1) that assigns a value to 
the function-identifier. The result of the function is the last value assigned. 
If no such assignment-statement exists, or if it exists but is not executed, the 
value returned by the function is unspecified. 
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If the function's identifier is used in a function-call within the function's 
blocks the function is executed recursively. 

Examples of function-declarations: 

function (nax(a: vector; n: integer): real; 
var X: real; 1: integer; 
begin 

X :- a[i]; 

for 1 := 2 to n do if X < a[i] then x := a[il 

max := X 
end; 

function power(x: real; y: integer): real; { y >= 0} 
var i^z: real; i: integer; 
begin 
w := X; z := 1; i := y; 
ifhile i > do begin 
{z*(ir«*i) = X ** y } 
if odd(i) then z := z*w; 
i := i div 2; 
w := sqrCw) 
end; 

{z = x**y } 
power := z 
end; 

A function can be declared forward in the same manner as a procedure (see 
Section 7.1 above). This permits mutual recursion. 

A function-declaration that has external Instead of a block defines the Pascal 
Interface to a separately compiled or assembled external routine (a PUNC in 
the case of assembly language). See the explanation in Section 7.1 above. 

73 Parameten 

A formal-parameter-list may be part of a procedure-declaration or 
function-declaration^ or it may be part of the declaration of a procedural or 
functional parameter. 

If it is part of a procedure-declaration or function-declaratioa it declares the 
formal parameters of the procedure or function. Each parameter so declared 
is local to the procedure or function being declared, and can be referenced by 
its identifier in the block associated with the procedure or function. 

If it is part of the declaration of a procedural or functional parameter, it 
declares the formal parameters of the procedural or functional parameter. In 
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this case there is no associated block and the identifiers of parameters in the 
formal-parameter-list are not significant (see Sections 73.3 and 7.3.4 below). 



formal-parameter-list 



parameter-declaration 



■^ 



^ procedure-heading 



^ function-heading 



o 



kD-^ 



paranKWr-aeciamUm » p clenUfier-list } -»(7)-» rtype-idenUfier 



var 



There are four kinds of parameten: ualue parameters, variable parameters, 
proceckiral par&wters, and functional parameters They are distinguished as 
follows: 

• A parameter-group preceded by var is a list of variable parameters. 

• A parameter-group without a preceding var is a list of value parameters. 

• A procedure-heading or function-heading denotes a procedural or functional 
parameter; see Sections 7.3.3 and 7.3.4 below. 

NOTE 

The types of formal-parameters are denoted by type-identifiers. In 
other words, only a simple identifier can be used to denote a type in a 
formal-parameter-list. To use a type such as arra)(0..255] of char as 
the type of a parameter, you must declare a type-identifier for this 
type: 

type charray = array[0. .255] of char; 

The identifier charray can then be used in a formal-parameter-list to 
denote the type. 
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NOTE 

The word file (for an "untyped" file) is not allowed as a type-identifier 
in a parameter-declaratioa since it is a reserved word. To use a 
parameter of this type, declare some other identifier for the type file 
—for example, 

type ptiyle = f lie; 

The identifier phyle can then be used in a formal-parameter-list to 
denote the type file. 

7.3.1 Value Parameters 

For a value-parameter, the corresponding actual-parameter in a procedure- 
statement or function-call (see Sections 5.2 and 6.1.2) must be an expression, 
and its value must not be of file-type or of any structured-type that contains 
a file-type. The formal value-parameter denotes a variable local to the 
procedure or function. The current value of the expression is assigned to the 
formal value-parameter upon activation of the procedure or function. The 
actual-parameter must be assignment-compatible with the type of the formal 
value-parameter. 

73.2 variable Parametere 

For a variable-parameter, the corresponding actual-parameter in a procedure- 
statement or function-call (see Sections 5.2 and 6.1.2) must be a variable- 
reference. The formal variable-parameter denotes this actual variable during 
the entire activation of the procedure or function. 

Within the procedure or function, any reference to the formal variable- 
parameter is a reference to the actual-parameter itself. The type of the 
actual-parameter must be identical to that of the formal variable-parameter. 

NOTE 

If the reference to an actual variable-parameter involves indexing an 
array or finding the object of a pointer, these actions are executed 
before the activation of the procedure or function. 

Components of variables of any packed structured type (including string-types) 
cannot be used as actual variable parameters. 

7.3.3 Procedural Parameters 

When the formal-parameter is a procedure-heading, the corresponding actual- 
parameter in a procedure-statement or function-call (see Sections 5.2 and 6.1.2) 
must be a procedure-identifier. The identifier in the formal procedure-heading 
represents the actual procedure during execution of the procedure or function 
receiving the procedural parameter. 
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Exanrple of pwcecfural paiameters: 

program passProc; 
var i: integer; 

procedure a(procedure x) {x is a formal procedural parameter.} 
begin 
write('At)out to call x "); 
X {call the procedure passed as parameter} 
end; 

procedure b; 
begin 

write("In procedure b') 
end; 

function c(procedure x): integer; 
begin 

X; {call the procedure passed as parameter} 

c:=2 
end; 

begin 

a(b); {call a, passing b as parameter} 

i:= c(b) {call c, passing b as parameter} 
end. 

If the actual procedure and the formal procedure have formal-parameter-lists, 
the formal-parameter-lists must be compatible (see Section 7.35). However, 
only the identifier of the actual procedure is written as an actual parameter; 
any formal-parameter-list is omitted. 

Ex&nple of procedural parameters with their own fomnal-parcgneter-llsts: 

program test; 
procedure xAsPar(y: Integer); 
begin 

ia"iteln('y=', y) 
end; 

procedure callProc(procedure xAgain(z: integer)); 
begin 

xAgain(l) 
end; 

begin {body of program} 

callProc(xftsPar) 
end. 

If the procedural parameter, upon activation, accesses any non-local entity (by 
variable-reference, procedure-statement, function-call, or label), the entity 
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accessed must be one that was accessible to the procedure when the procedure 
was passed as an actual parameter. 

To see what this means^ consider a procedure pp which is known to another 
procedure, flrstPasser. Suppose that the following sequence takes place: 

1. firstPasser is executing. 

2. flrstPasser calls a procedure named flntReceiver, passing pp as an 
actual parameter. 

3. firstReceiver calls secondReceiver, again passing pp as an actual 
parameter. 

4. secondReceiver calls pp (first execution of ppX 

5. secondReceiver calls thlrdRecelver, again passing pp as an actual 
parameter. 

6. thirdReceiver calls firstPasser (indirect recursion), and passes pp to 
firstPasser as an actual parameter. 

7. firstPasser (executing recursively) calls pp (second execution of pp). 

Thus the procedure pp is called first from secondReceiver, and then from the 
second (recursive) execution of firstPasser. 

Suppose that pp accesses an entity named xx)c which Is not local to pp; and 
suppose that each of the other procedures has a local entity named xxx. 

Each time pp Is called, which xxx does It access? The answer Is that In eacn 
case, pp accesses the xxx that Is local to the /7rst execution of flntPasser— 
that Is, the xxx that was accessible when pp was originally passed as an actual 
parameter. 

7.3.4 Functional Parameten 

When the formal parameter is a function-heading, the actual-parameter must 
be a function-Identifier. The identifier In the formal function-heading 
represents the actual function during the execution of the procedure or 
function receiving the functional parameter. 

Functional parameters are exactly like procedural parameters, with the 
additional rule that corresponding formal and actual functions must have 
IcfenUcal result-types. 

7.3.5 Parameter List Compatibility 

Parameter list compatibility is required of the parameter lists of corresponding 
formal and actual procedural or functional parameters. 
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Two formal-parameter-lists are compatible if they contain the same number of 
parameten and if the parameten in corresponding positions match. Two 
parameters match if one of the following is true: 

• They are both value parameters of identical type. 

• They are both variable parameters of identical type. 

• They are both procedural parameters with compatible parameter lists. 

• They are both functional parameters with compatible parameter lists and 
identical result-types. 
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8.1 Syntax 

A Pascal program has the form of a procedure declaration except for its 
heading and an optional uses-cJausa 

pwgran} 

program-heading "~*\y)" 



t: 



uses-clause 



Y^ 



block 



procfram-heaOIng 

— »( program) -» identifier -y 



^"-(xy^ program-parameters 



H^' 



pwcitam-pammeteis J icenOfier-iist 



uses-Clause 



» ( uses^ 



identifier- list 



The occurrence of an identifier immediately after the word program declares it 
as the program's identifier. 

The uses-clause identifies all units required by the program, including units 
that it uses directly and other units that are used by those units. 

a2 Program-Parameters 

Currently, any program-parameters are purely decorative and are totally 
ignored by the compiler. 

8.3 Segmentation 

The code of a program's main body is always placed in a run-time segment 
whose name is a string of blanks (the "blank segment"). Any other block can 
be placed in a different segment by using the $S compiler command (see 
Chapter 12 and Appendix A). If no $S command is used in the program, all 
code is placed in the blank segment. Code from a program can be placed in 
the same segment with code from a regular-unit, but it cannot be mixed with 
code from an intrinsic-unit (see Chapter 9). 
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A unit Is a separately complied, non-executable object file that can be linked 
with other object files to produce complete programs. There are two kinds of 
units, called neguJar-unJtswn intrlnsic-unitsi In the current implementation of 
the Workshop, you can use intrinsic-units that are provided, but you cannot 
write new ones. 

Each unit used by a program (or another unit) must be compiled, and its object 
file must be accessible to the compiler, before the host program (or unit) can 
be compiled. 

9.1 Regular-Unlls 

Regular-units can be used as a means of modularizing large programs, or of 
making code available for incorporation in various programs, without making 
the source available. 

When a program or unit (called the host) uses a regular-unit, the linker inserts 
a copy of the compiled code from the regular-unit into the host's object file. 

By default, the code copied from the regular-unit is placed in the blank 
segment (see Chapter 8). The code of the entire unit, or of blocks within the 
unit, can be placed in one or more different segments by using the $S compiler 
command (see Chapter 12). 

9.1.1 wnung Regular-Units 

The syntax for a regular-unit is: 



'^'^-^t » | unit-heading | -»(7) 



3 



^ interface-par t> | implementation-part K ^^idTy^?)-^ 



unlt-f^aainq ^^^e>4toUto 
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interface-pan ^ (1^;^^^^ 



T 



^ uses-Clause 



r 



^ constant-declaralion-part 



<~ 



b 



D 



^ lype-declaratlon-part 



r 






""-^ variable-declaratlon-part 



r 






M> procedure-and-functlon-declaration-part 



implementation-part^ ^ implementation > 



T 



^ constant-declaration-part 



r 



S^ type-declaration-part 



b 



r 



D 



""^ variafale-declaration-part 



r 



D 



^ procedure-and-function-declaration-part 



^i--> 



The interface-part declares constants, types, variables, procedures, and 
functions that are "public," i.e. available to the host 

The host can access these entities just as if they had been declared in the 
host Procedures and functions declared in the interface-part are abbreviated 
to nothing but the procedure or function name, parameter specifications, aid 
function result- type. 

NOTE 

Since the interface-part may contain a uses-clause, a unit can use 
another unit (see Section 9.3). 
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The implementaU QU-parL which follows the last declaration in the interface- 
part "beglr^l^rdeclarlng any constants, types, variables, procedures, or 
functions that are "private, " i.e. not available to the host 

j The public procedures and functions are re-declared in the implementation- 
\ part The parameters and function result types are omitted from these 
declarations, since they were declared in the interface-part, and the procedure 
and function blocks, omitted in the interface-part, are included in the 
implementation-part 

In effect, the procedure and function declarations in the interface are like 
forward declarations, although the forward directive is not used. Therefore, 
these procedures and functions can be defined and referenced in any sequence 
in the implementation. 

NOTES 

There is no "initialization" section in Pascal units on the Lisa (unlike 
Apple II and Apple III Pascal). If a unit requires initialization of its 
data, it should define a public procedure that performs the initialization, 
and the host should call this procedure. 

Also note that global labels cannot be declared in a unit 

A short example of a unit is: 

unit Simple; 

INTERFACE {public Objects declared} 

const FlrstValue=l; 

procedure AddOne(var Incr: Integer); 

function Addl(Incr : Integer) : Integer; 
IHPLEHENTAnON 

procedure AddOne; {note lack of parameters...) 
begin 

Incr:=lncr+1 
end; 
function Addl; {...and lack of function result type) 

begin 

Addl:=lncr+1 
end 
end. 

9.1^ Using Regular-units 

The syntax for a uses-clause is given in Section 8.1. Note that in a host 
program, the uses-clause (if any) must immediately follow the program- 
heading. In a host unit, the uses-clause (if any) Immediately follows the 
symbol interface. Only one uses-clause may appear in any host program or 
unit; it declares all units used by the host program or unit. 

See Section 9.3 for the case where a host uses a unit that uses another unit 
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It is necessary to specify the file to be searched for regular units. The $U 
compiler command specifies this file. See Chapter 12 for more details. 

Assume that the example unit Simple (see above) is compiled to an object file 
named APPL:SIMPLE.CBJ. The following is a short program that uses simple. 
It also uses another unit named Other^ which is in file APPL:OTHER.0BJ. 



program CallSlmple; 

uses {$U APPLrSIMPLE.OBJ} 

Simple^ 

{$U APPLrOTHER.OBJ} 
Other; 
var irint^r; 
begin 
l:=FirstValue; 
»rite("i+l is '^AddlCi)); 
write(xyz(i)) 
end. 



{file to search for units} 
{use unit Simple} 
{file to search for units} 
{use unit Other} 



{FirstValue is from Single} 
{Addl is defined in Simple} 
{xyz is defined in Other} 



9J2 Intrinsic-Units 

The only intrinsic-units you can use are the ones provided with the Workshop 
software. 

Intrinsic-units provide a mechanism for Pascal programs to share common code, 
with only one copy of the code in the system. The code is kept on disk, and 
when loaded into memory it can be executed by any program that declares the 
intrinsic-unit (via a uses-clause, the same as for regular-units). 

By default, the system looks up all intrinsic-units in the system Intrinsics 
library file, INTRINSICLIB. All intrinsic-units are referenced in this library, 
so the $U filename compiler command is not needed with intrinsic-units. 

93 Units that Use Other Units 

As explained above, the uses-clause in the host must name all units that are 
used by the host. Here "used" means that the host directly references 
something in the interface of the unit Consider the following diagram: 



Host Program 
uses unitA, unltB; 



unitA 



interface 
uses unitC; 



implementation 



units 



interface 



implementation 



unite 



interface 



implementation 
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The host program directly references the interfaces of unltA and unitB; the 
uses-clause names both of these units. The implementation-part of unitA also 
references the interface of unitC^ but it is not necessary to name unite in the 
host-program's uses-clause. 

In some cases^ the uses-clause must also name a unit that is not directly 
referenced by the host. The following diagram is exactly like the previous one 
except that this time the Interface of unltA references the interface of unite, 
and unite must be named in the host-program's uses-clause. Note that unite 
must be named before unltA. 



Host Program 
uses unltc^ unitA, 
unitB; 





unitA 


;f 


Interface 
uses unitC; 


1/ 


implementation 






\ 


unitB 


>* 


interface 




implementation 



unite 



interface 



implementation 



In a case like this, the documentation for unitA should state that unite must 
be named in the uses-clause before unitA 
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Input/Output 

This chapter describes the standard C't)uilt-in") I/O procedures and functions of 
Pascal on the Lisa 

Standard procedures and functions are predeclared. Since all predeclared 
entities act as if they were declared in a "block" surrounding the program, no 
conflict arises from a declaration that redefines the same Identifier within the 
program. 

NOTE 

Standard procedures and functions cannot be used as actual procedural 
and functional parameters. 

This chapter and Chapter 11 use a modified BNF notation, instead of syntax 
diagrams, lo indicate the syntax of actual-parameter-llsts for standard 
procedures and functions. 

ExarrpJa- 

Par&neter List new(p [, tl, ... t/?]) 

This represents the syntax of the actual-parameter-list of the standard 
procedure new, as follows: 

• p, tl, and t/7 stand for actual-parameters. Notes on the types and 
interpretations of the parameters accompany the syntax description. 

• The notation tl, ... \n means that any number of actual-parameters can 
appear here, separated by commas. 

• Square brackets [ ] indicate parts of the syntax that can be omitted. 

Thus the syntax shown here means that the p parameter is required. Any 
number of t parameters may appear, with separating commas, or there may be 
no t parameters. 

10.1 Introduction to I/D 

This section covers the I/O concepts and procedures that apply to all file types. 
This includes the types text (see Section 10.3) and "untyped" files (see Section 
10.4). 

To use a Pascal file variable (any variable whose type is a file-type). It must 
be associated with an external file. The external file may be a named 
collection of information stored on a peripheral device, or (for certain file- 
types) it may be the peripheral device itself. 

The association of a file variable with an external file is made by opening the 
file. An existing file is opened via the reset procedure, and a new file is 
created and opened via the rewrite procedure. 
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NOTE 

Pascal on the Lisa does not provide automatic I/O checking. To check 
the result of any particular I/O operation use the loresult function 
described in Section 10.1.6. 



iai.l Device Types 

For purposes of Pascal I/O, there are two types of peripheral devices: 

• A ffle-structurecf device is one that stores files of data, such as a diskette. 

• A character device is one whose input and output are streams of individual 
bytes, such as the Lisa screen and keyboard or a printer. 

iaL2 External File Species 

There are three "species" of external files that can be used in Pascal I/O 
operations: 

• A dataflle is any file that is stored on a file-structured device and was 
/3«£7/ originally created in association with a file variable of type text 

• A textfile is a file that is stored on a file-structured device and was 
originally created in association with a file variable of type text Textfiles 
are stored in a specialized format (see Section 10.3). 

• A character ctevJce cm be treated as a file. 

Table 10-1 summarizes the effects of all possible combinations of different file 
variable types and external file species. The "ordinary cases" in the table 
reflect the basic intent of the various file-types. Other combinations, such as 
block-oriented access to a textfile via a variable of type file, are legal but 
may require cautious programming. 
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Table 10-1 

Combinations of File Viable Types with External File Species 

and Categories 





var f: file of 

someType; 


var f : text; 


var f : file; 


datafile 


Ordinary case. 
After reset, 
f * - 1st record 
file. 


(Textfile format 
assumed!) After 
resets f * is 
unspecified. 


Ordinary case. 
Block access. 


textfile 


(Textfile format 
not assumed!) 
After reset*, 
f " = 1st record 
of file (as 
declared). 


Ordinary case. 
Textfile format 
assumed. After 
reset, f " is 
unspecified. 


(Textfile format 
not assumed!) 
Block access. 


character 
device 


After reset, 
f " = 1st char, 
from device 
(system waits for 
it!). I/O error If 
file record type 
not byte-sized. 


ordinary case. 
After reset 
f " is unspeci- 
fied (no wait 
for input char). 


Block access, 
if allowed by 
device. 


* In tttese cases, the Janestat function will letian a "warning" 
(I.e., a negative numt?erj immediately after the reset cperation. 



10.13 The Reset Procedure 

Opens an existing file. 

Parameter List reset(f, title) 

1. f is a variable-reference that refers to a variable of file-type. The file 
must not be open. 

2. title is an expression with a string value. The string should be a valid 
pathname for a file on a file-structured device, or a pathname for a 
character device. 
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Both parameters are required (unlike Apple II and Apple III Pascal, 
where the second parameter is optional). 

Reset(t title) finds an existing external file with the pathname title, and 
associates f with this external file. (If there is no existinq external file with 
the pathname title, an I/O error occurs; see Section 10.1.6.) 

If title is the pathname of a character device, then 

• Eof(f) becomes false. 

• If f is of type text, the value of f " is unspecified. The next read or readln 
on f will wait until a character is available for input, and begin reading 
with that character. 

• If f is of type file and the device is one that allows block access, there is 
no file buffer variable f" and the "current file position" is set to the first 
block (block 0) of the file. If the device does not allow block access, an 
I/O error occurs (see Section 10.1.6). 

• If f is not of type text or file, its component-type must be a "byte-size" 
type such as the type -12a.l27. Note that char is not a byte-size type! If 
the component-type of f is not byte-size, an I/O error occun (see Section 

10.1.6). 

If no I/O error occurs, the system waits until a character is available from 
the device and then assigns the character's 8-bit code to f ". 

If title is the pathname for an existing file on a file-structured device, then 

• Eofl[f) becomes false if the external file is not empty. If the" external file 
is empty, eof(f) becomes true. 

• If f is not of type text or file, reset sets the "current file position" to the 
first record in the external file, and assigns the value of this record to the 
file buffer variable f *. If the external file is a textflle, the ioresult 
function will return a negative number as a warning (see Section 10.1.6X 

• If f is of type text, the value of f " is unspecified. If the file is a textfile, 
the next read or readln on f will begin at the first character of f. If the 
file is a datafile, it will be treated as if it were a textfile (see Section 
10.3) and the ioresult function will return a negative number as a warning 
(see Section 10.1.6). 

• If f is of type file, there is no file buffer variable f" and the "current file 
position" is set to the first block (block 0) of the file. 
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iai.4 The Rewrite Procedure 

Creates and opens a new file. 

Parameter List' reirite(f, title) 

1. f is a variable-reference that refers to a variable of file-type. 

2. title is an expression with a string value. The string should be a valid 
pathname for a file on a file-structured device^ or a pathname for a 
Character device. 

If f is already open^ an I/O error occurs (see Section 10.1.6). 

If title is the pathname of a character device^ then 

• Eoftf) becomes false. 

• Rewrite(t title) simply associates f with the device and opens f. 

• The status of the device is not affected. 

• The value of f " becomes unspecified. 

If title is the pathname for a new file on a file-structured device^ then 

• Eof(f) becomes true. 

• Rewrite(f, title) creates a new external file with the pathname title, and 
associates f with the external file. This is the only way to create a new 
external file. 

• The species of the new external file is set according to the type of f— 
"textfile" for type text, or "datafile" for any other type. 

• The value of f * becomes unspecified. 

• If f is not of type file, the "current file position" is set to just before the 
fint record or character position of the new external file. 

• If f is of type file, the "current file position" is set to block (the first 
block in the file). 

• If f is subsequently closed with any option other than lock or crunch (see 
Section 10.1.5), the new external file is discarded at that time. Closing f 
with lock or crunch is the only way to make the new external file 
permanent. 

• If title is the pathname of an existing external file, the existing file will be 
discarded only when f is subsequently closed with the lock or crunch option 
(see section 10.1.5). 

Unspecified effects are caused if the current file position of a file f is altered 
while the file-buffer f ' is an actual variable parameter, or an element of the 
record-variable-reference list of a with-statement, or both. 
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iai.5 TTie Close Procedure 

Closes a file. 

Parameter List close(f {, option]) 

1. f is a variable-reference that refers to a variable of file-type. 

2. option (may be omitted) is an identifier from the list given below. If 
omitted^ the effect is the same as using the identifier normal. 

Close(f, option) closes t if f is open. The association between f and its 
external file is broken and the file system marks the external file "closed". If 
f is not open^ the close procedure has no effect 

The option parameter controls the disposition of the external file, if it is not a 
character device. If it is a character device, f is closed and the status of the 
device is unchanged. 

The identifiers that can be used as actual-parameters for option are as follows: 

• normal ~ If f was opened using rewrite, it is deleted from the directory. 
If f was opened with reset, it remains in the directory. This is the default 
option, in the case where the option parameter is omitted. 

• lock ~ If the external file was opened with rewrite, it is made permanent 
in the directory. 

If f was opened with rewrite and a title that matches an existing file, the 
old file is deleted (unless the safety switch is "on"). If the old file has the 
safety switch "on," it remains in the directory and the new file is deleted. 

If f was opened with reset, a normal close is done. 

• purge — The external file is deleted from the directory (unless the safety 
switch is "on"). In the special case of a file that already exists and is 
opened with rewrite, the original file remains in the directory, unchanged. 

• crunch — This is like lock except that it locks the end-of-file to the point 
of last access; i.e., everything after the last record or character accessed is 
thrown away. 

All closes regardless of the option will cause the file system to mark the 
external file "closed" and will make the value of f * unspecified. 

If a program terminates with a file open (i.e., if close is omitted), the system 
automatically closes the file with the normal option. 

NOTE 

If you open an existing file with reset and modify the file with any 
write operation, the contents are immediately changed no matter what 
close option you specify. 
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iaL6 The loresult FincUon 

Pascal on the Lisa does not provide automatic 1/0 checking. To check the 
result of any particular lA) operation, you must use the loresult function. 

Result type: integer 

Parameter List- no parameters 

loresult returns an integer value which reflects the status of the last com- 
pleted 1/0 operatioa The codes are given in the Workshop User's Guide for the 
Lisa. Note that the code indicates successful completion, positive codes 
indicate errors, and negative codes are "warnings" (see Table 10-1). 

Note that the codes returned by loresult are not the same as the codes used in 
Apple II and /^ppie HI Pascal. 

NOTES 

The read, readin, write, and writeln procedures described in Section 10.3 
may actually perform multiple I/O operations on each call. After one of 
these procedures has executed, loresult will return a code for the status 
of the last of the multiple operations. 

Also, beware of the following common error in diagiostic code: 

read(foo); 

•riteln( * ioresult= ' , loresult) 

The intention is to write out the status of the read operation, but 
instead the status written out will be that of the write operation on the 
string 'loresult-'. 

iai.7 The Eof Function 

Detects the end of a file. 

Result Type: txx)lean 

F^arameter List- eof [(f)] 

1. f is a variable-reference that refers to a variable of file-type. 

If the parameter-list is omitted, the function is applied to the standard file 
input (see Section 10.3). 

After a get or put operation, eof(f) returns true if the current file position is 
beyond the last external file record, or the external file contains no records; 
otherwise, eof(f) returns false. Specifically, this means the following: 

• After a get, eof(f) returns true if the get attempted to read beyond the last 
file record (or the file is empty). 

• After a put, eof(f) returns true if the record written by the put is now the 
last file record. 
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If f is a character device^ eofl(f) will always return false. 

See Section 103 for the behavior of eof(f) after a read or readln operation. 

NOTE 

Whenever eof[f) is true, the value of the file buffer variable f " is un- 
specified. 

10.2 RecQid-Qriented I/O 

This section covers the get put and seek procedures, which perform record- 
oriented I/O; that is, they consider a file to be a sequence of variables of the 
type specified in the file-type. These procedures are not allowed with files of 
type file. 

The effects of get and put are unspecified with files of type text, and seek has 
no effect with files of type text The text type is supported by specialized 
procedures described in section 10.3. 

ia2.l The Get Procedure 

Reads the next record in a file. 

Parameter List get(f) 

1. f is a variable-reference that refers to a variable of file-type. The file 
must be open. 

If eof(f) is false, get(f) advances the current file jjosition to the next file 
record, and assigns the value of this record to f . If no next component 
exists, then eof(f) becomes true, and the value of f " becomes unspecified. 

If eof(f) is true when get(f) is called, then eof(f) remains true, and the value of 
f " becomes unspecified. 

If the external file is a character device, eof(f) is always false and there is no 
"current file position." In this case, get(f) waits until a value is ready for input 
and then assigns the value to f ". 

10.2.2 TTie Put Procedure 

Writes the current record in a file. 

Parameter List put(f) 

1. f is a variable-reference that refers to a variable of file-type. The file 
must be open. 

If eof(f) is false, put(f) advances the current file position to the next file 
record and then writes the value of f " to f at the new file position. If the 
new file position is beyond the end of the file, eof(f) becomes true, and the 
value of f * becomes unspecified. 

If eof(f^ is true, put(0 appends the value of f " to the end of f and eof(0 
remains true. 
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If the external file is a character device, eof(f) is always false, there is no 
"current file position;* and the value of f * is sent to the device. 



"current file position," 

NOTE 



If put is called immediately after a file is opened with reset, Uie put 
will write the second record of the file (since the reset sets the 
current position to the first record and put advances the position before 
writing). To get around this gBid write the fint record, use the seek 
procedure (see Section 10.2.3). 

1023 The Seek Procedure 

Allows access to an arbitrary record in a file. 

Parameter UsL- seek(f^ n) 

1. f is a variable-reference that refers to a variable of file-type. The file 
must be open. 

2. n is an expression with an Integer value that specifies a record number in 
the file. Note that records in files are numbered from 0. 

If the file is a character device or is of type text seek does nothing, 
otherwise, seek(f, n) affects the action of the next get or put from the file, 
forcing it to access file record n instead of the "next" record. Seek(f, n) does 
not affect the file-buffer f *. 

A get or put must be executed between seek calls. The result of two con- 
secutive seeks with no intervening get or put is unspecified. Immediately after 
a seek(f, n), eof(f) will return false; a following get or put will cause eof to 
return the appropriate value. 

NOTE , 

The record number specified in a seek call is not checked for validity. 
If the number is not the number of a record in the file and the program 
tries to get the specified record, the value of the file-buffer becomes 
unspecified and eof becomes true. 

ia3 Text-Orlented I/O 

This section describes input and output using file variables of the standard type 
text Note that in Pascal on the Lisa, the type text is distinct from file of 
char (see Section 3.2.4). 

When a text file is opened, the external file is interpreted in a special way. It 
is considered to represent a sequence of characters, usually formatted into 
Jj'nes by CR characters (ASCII 13). 

The Lisa keyboard and the workshop screen appear to a Pascal program to be 
built-in files of type text named Iniput and output respectively. These files 
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need not be declared and need not be opened with reset or rewrite, since they 
are always open. 

When a program is taking input from input, typed characters are echoed on the 
Workshop screen. In addition to the input file, the Lisa keyboard is also 
represented as the character device -KEYBOARD. To get keyboard input 
without echoing on the screen, you can open a file variable of type text with 
-KEYBOARD as the external file pathname. 

Other interactive devices can also be represented in Pascal programs as files of 
type text 

When a text file is created on a file-structured device, the external file is a 
textfile. It contains information other than the actual sequence of characters 
represented, as follows: 

• The stored file is a sequence of 1024-byte p^es. 

• Each page contains some number of complete lines of text and is padded 
with null characters (ASCII 0) after the last line. 

• Two 512-byte header blocks are also present at the beginning of the file. 

• A sequence of spaces in the text may be compressed into a two-byte code, 
namely a CLE chafacter{f^O\\ 16) followed by a byte containing 32 plus 
the number of spaces represented. 

All of this special formatting is invisible to a Pascal program if the file is 
accessed via a file variable of type text (but visible via a file variable of any 
other file-type)L 

Certain things that can be done with a record-structured file are impossible 
with a file variable of type text 

• The seek procedure does nothing with a file variable of type text 

• The effects of get and put are unspecified with a file variable of type text 

• The contents of the file buffer variable are unspecified with a file variable 
of type text 

• A file variable of type text that is opened with reset cannot be used for 
output, and one opened with rewrite cannot be used for input. Results are 
unspecified if either of these operations is attempted. 

In place of these capabilities, text-oriented I/O provides the following: 

• Automatic convenion of each input CR character into a space. 

• The eoln function to detect when the end of an input line has been 
reached. 

• The read procedure, which can read cMar values, string values, pact^d array 
of char values, and numeric values (from textual repfiresentations). 
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• The write procedure^ which can write char values, string values, packed 
array of char valies, numeric values, and tioolean values (as textual 
representatlonsX 

• Line-oriented reading and writing via the readln and writeln procedures. 

• The page procedure, which outputs a form-feed character to the external 
file. 

• Automatic conversion of input DLE-codes to the sec^<ences of spaces that 
they represent. Note that output sequences of spaces are not converted to 
DLE-codes. 

• Automatic skipping of header blocks and null characters during input 

• Automatic generation of textfile header blocks, and automatic padding of 
textfile pages with null characters on output 

10.3.1 TTie Read Procedure 

Reads one or more values from a text file into one or more program variables. 

Parameter LJsL- read( [f, ] vl [, v2, . . . v/?] ) 

The syntax of the parameter-list of read allows an indefinite number of 
actual-parameters. Consecutive actual-parameters are separated by commas, 
just as in a normal parameter-list 

1. f (may be omitted) is a variable-reference that refers to a variable of 
type text The file must be open. If f is omitted, the procedure reads 
from the standard text file Input which represents the Lisa keyboard. 

2. vl ... v/7 are input varlablesi Each is a variable parameter, used as a 
destination for data read from the file. Each input variable must be a 
variable-reference that refers to a variable of one of the following types: 

• char, integer, or longlnt (or a subrange of one of these) 

• real 

• a string-type or a packed array of char type. 

These are the types of data that can be read (as textual representations) 
from a file. At least one input variable must be present 

Read(f,vU..,v/7) is equivalent to: 

begin 
read(f,vl); 

read(f,v/7) 
end 
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NCmE 

Read can also be used to read from a file fil that Is not a text file. In 
this case read(filp() is equivalent to: 

begin 

X := fll"; 

get(fii) 
end 



103.1.1 Read with a Char Variable 

If f is of type text and v is of type char, the following things are true 
immediately after read(f,v): 

• Eof(f) will return true if the read attempted to read beyond the last 
character in the external file. 

• Eoln(f) will return true^ and the value of v will be a space^ if the character 
read was the CR character. Eoln(f) will also return true if eof(f) is true. 

ia3.1.2 Read with an Integer or Longint variable 

If f is of type text and v is of type integer, subrange of integer, or longint, 
then read(f,v) implies the reading from f of a sequence of characters that form 
a signed whole number according to the syntax of Section 1.4 (except that 
hexadecimal notation is not allowed). If the value read is assignment- 
compatible with the type of v, it is assigned to v; otherwise an error occun. 

In reading the sequence of characters, preceding blanks and CRs are skipped. 
Reading ceases as soon as a character is reached that, together with the 
characters already read, does not form part of a signed whole number. 

An error occurs if a signed whole number is not found after skipping any 
preceding blanks and CRs. 

If f is of type text, the following things are true immediately after read(f,v): 

• Eof(f) will return true if the last character in the numeric string was the 
last character in the external file. 

• Eoln(f) will return true if the last character in the numeric string was the 
last character on the line (not counting the CR character). Eoln(f) will also 
return true if eof(f) Is tiue. 

ia3.L3 Read with a Real Viable 

If f is of type text and v is of type real, then read(f,v) Implies the reading 
from f of a sequence of characters that represents a real value. The real 
value is assigned to the variable v. 

In reading the sequence of characters, preceding blanks and CRs are skipped. 
Reading ceases as soon as a character is reached that, together with the 
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characters already read, does not form a valid representation. A "valid 
representation" is either of the following: 

• A finite real integer, or longint value represented according to the 
signed-number syntax of section 1.4 (except that hexadecimal notation is 
not allowed). An integer or longint value is converted to type reaL 

• An infinite value or Nan represented as described in Appendix D. 

An error occurs if a valid representation is not found after skipping aiy 
preceding blanks and CRs. 

Immediately after read(f,v) where v is a real variable, the status of eof(f) and 
eoln(f) are the same as for an integer variable (see Section 10.3.1.2 above). 

103.1.4 Read With a String Viable 

If f is of type text and v is of string-type, then read(f>/) implies the reading 
from f of a sequence of characters up to txjt not including the next CR or 
the end of the file. The resulting character-string is assigned to v. An error 
occurs if the number of characters read exceeds the size attribute of v. 

NOTE 

Read with a string variable does not skip to the next line after reading, 
and the CR is left waiting in the input buffer. For this reason, you 
cannot use successive read calls to read a sequence of strings, as they 
will never get past the first CR ~ after the first read, each subsequent 
read will see the CR and will read a zero-length string. 

Instead, use readln to read string values (see Section 10.3.2). Readln 
skips to the beginning of the next line after reading. 

The following things are true imnnediately after read(tv) 

• Eof(f) will return true if the line read was the last line in the file. 

• Eoln(f) will always return true. 

10.3.1.5 Read with a Packed Array of Char Viable 

If f is of type text and v is a packed array of char, then read(f,v) implies the 
reading from f of a sequence of characten. Characters are read into 
successive character positions in v until all positions have been filled, or until 
a CR or the end of the file is encountered. If a CR or the end-of-file is 
encountered. It is not read into v; the remaining positions in v are filled with 
spaces. 
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ia3^ "me Readln Procedure 

The readln procedure is an extension of read. Essentially it does the same 
thing as read, and then skips to the next line in the input file. 

Parameter List: The syntax of the parameter list of readln is tJie same as that 
of read^ except as follows: 

• A readln call with no input variables is allowed. Exanple: 

readme sourcef lie) 

• The parameter-list can be omitted altogether. 

If the first parameter does not specify a file^ or if the parameter-list is 
omitted, the procedure reads from the standard file Input, which represents the 
Lisa keyboard. 

Readin(fX with no input-variables, causes a skip to the beginning of the next 
line (if there is one, else to the end-of-flle). 

Readln can onlytxQ used on a text file. Except for this restriction, 
readln(f,vl,...,v/7) is equivalent to: 

begin 

read(f,v1 ,v/7); 

readln(f) 
end 

The following things are true immediately after readln(f;v)i, regardless of the 
type of V: 

• Eof(f) will return true if the line read was the last line in the external file. 

• Eoln(f) will always return falsa 

1033 The Write Procedure 

Writes one or more values to a text file. 

Parameter List' i»rite([f, ] pi [^ p2^ ... p/?]) 

The syntax of the parameter list of write allows an indefinite number of 
actual-parameters. 

1. f (may be omitted) is a variable-reference that refers to a variable of 
type text The file must be open. If f is omitted, the procedure writes to 
the standard file output, which represents the Workshop screen. 

2. pi ... p/zare output-specs Each output-spec includes an output 
expression whose value is to be written to the file. As explained below, 
an output-spec may also contain specifications of field-width and number 
of decimal places. Each output expression must have a result of type 
integer, longint, real, boolean, char, a string-type, or a packed array of 
char type. These are the types of data that can be written (as textual 
representations) to a file. At least one output-spec must be present. 
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Write(f43U-4)/7) is equivalent to: 

begin 
•rite(f^pl); 

•rite(f,p/7) 
end 

Immediately after write(<X both eof(f) and eoln(f) will return tiue. 

NOTE 

Write can also be used to write onto a file fll that is not a text file. 
In this case write(fllp() is equivalent to: 

begin 

fU" := x; 

put(fll) 
end 

103.3.1 Output-Specs 

Each output-spec has the form 

OutExpr [ : MinWldth [ : DecPlaces] ] 

where OutE)g)r is an output expression. MinWidth and DecPlaces are 
expressions with integer or longint values. 

MinWidth specifies the minimum field width, with a default value that 
depends on the type of the value of OutExpr (see below). MinWidth should be 
greater than zero; otherwise, the results are unspecified. Exactly MinWidth 
characters are written (using leading spaces if necessary), except when OutExpr 
has a numeric value that requires more than MinWidth characters; in this 
case, enough characters are written to represent the value of OutExpr. 

DecPlaces specifies the number of decimal places in a fixed-point repre- 
sentation of a real value. It can be specified only if OutExpr has a real value, 
and if MinWidth is also specified. If DecPlaces is not specified, a floating- 
point representation is written. 

10.33.2 Write with a Char value 

If OutExpr has a char value, the character is written on the file f. The default 
value for MinWidth is one. 

ia333 Write with an Integer or Longint value 

If OutExpr has an integer or lonc^t value, its decimal representation is written 
on the file f. The default value for MinWidth is 8. The representation consists 
of the digits representing the value, prefixed by a minus sign if the value is 
negative, and any leading spaces that may be required to satisfy MinWidth. If 
the representation requires more than MinWidth characters, MinWidth is 
ignored. 
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1033.4 Write with a Real V^ue 

If OutExpr has a real value^ the default value for MinWidth is 12. 

If QutExpr has an infinite value, it is output as a string of at least two "+" 
characters or at least two "-" characters. If OutExpr is a NaN, it is output as 
the character string "NaN", possibly followed by a string of characters enclosed 
ti'j single-quotes. See Section 10.3.3.5 for details on string output 

If OutExpr has a zero value, it is represented as "0" or "-0". 

If OutExpr has a finite value, its decimal representation is written on the file 
f. This representation is the nearest possible decimal representation, depending 
on MlnWldth and DecPlaces. If the unrounded value is exactly halfway 
between two possible representations, the representation whose least significant 
digit Is even Is written out. 

If OecPlaces Is not specified, a /7<c»/y/y-ya7y/7^ representation is written as 
follows: 

• If MinWidth is less than 6, then its value Is set to 6 (internally). This Is the 
minimum usable width for writing a floating-point representation. 

• If the sign of the value of OutExpr Is negative, a minus sign Is written; 
otherwise, a space is written. 

• If MinWidth > 8, the significant digits are written with one digit to the left 
of the decimal point and (MinWidth - 7) digits to the right of the decimal 
point. 

• If MinWidth < 8, the most significant digit Is written and the decimal point 
is omitted. 

• The exponent Is written as the letter "E", an explicit "+" or "-" sign, and 
two digits. 

If DecPlaces Is specified, a fixecf-point representation Is written as follows: 

• Enough leading spaces are written to satisfy MinWidth. 

• If the value is negative, the minus sign "-" Is written; If It Is not negative, 
a space Is written. 

• If DecPlaces > 0, the significant digits are written with the Integer part of 
the value to the left of the decimal point. The next DecPlaces digits are 
written to the right of the decimal point 

• If DecPlaces < 0, only the Integer part of the value Is written and no 
decimal point is written. 

10.3.35 Write With a String VMue 

If the value of OutExpr is of string type with length L, the default value for 
MinWidth is L If MlnWidth>-L, the value is written on the file f preceded by 
(MInWidth-L) spaces. If MinWidth<L, the first MinWidth characten of the 
string are written. 
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1033^ Write with a Packed Array of Char Vdlue 

If E is Of type packed array of char, the effect is the same as writing a string 
whose length is the number of elements in the array. 

ia3.3.7 write with a Boolean v^ue 

If the value of OutExpr is of type t)oolean, the string " TRUE" (with a leading 
space) or the string "FALSE" is written on the file f. The default value of 
MinWldth is 5. If MlnWldth>5, leading spaces are added; if MlnWldth<5, the 
first hllnWldth characters of the string are written. This is equivalent to: 

•rlte(f/ TRUE':MinWidth) 

or 
i»rite(f, 'FALSE' rMlnWidth) 

10.3.4 The Writeln Procedure 

The writeln procedure is an extension of write. Essentially It does the same 
thing as write, and then writes a CR character to the output file (ending the 
line). 

Parameter List- The syntax of the parameter list of writeln is the same as 
that of write, except as follows: 

• A writeln call with no output-specs is allowed. Example: 

witeln(outputf 1 le) 

• The parameter-list can be omitted altogether. 

If the first parameter does not specify a file, or if the parameter-list is 
omitted, the procedure writes to the standard file output, which represents the 
Workshop screen. 

Writeln(f) writes a CR character to the file f. 

Writeln can onlyX^B used on a text file. Except for this restriction, 
wrlteln(fjpl,...4)/7) is equivalent to: 

begin 

iwrite(f,pl, ...,p/7); 

writelnCf) 
end 

Immediately after writeln(f% both eof(f) and eoln(f) will return tnj& 

ia3.5 The Eoln Function 
Result Type: boolean 

Parameter List: eoln[(f)] 

1. f is a variable-reference that refers to a variable of type text The file 
must be open. 

The actual-parameter-list can be omitted entirely. In this case, the function is 
applied to the standard file input (the Lisa keyboard). 
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Eoln(f) returns true "if the end of a line has been reached in f." The meaning 
of this depends on whether the external file is a character device, on which I/O 
procedure was executed last, and on what type of variable was used to receive 
an input value. For details, see Sections 10.3.1 through 10.3.4. 

The end of the file is considered to be the end of a line; therefore eoln(f) will 
return true whenever eof(f) is true. 

10.3.6 The Page Procedure 
Parameter List- page(f) 

1. f is a variable-reference that refers to a variable of type text The file 
must be open. 

The actual-parameter f cannot be omitted. Page(f) outputs a form-feed 
character to the file f. This will cause a skip to the top of a new page when 
f is printed. 

Note that page(output) sends a form-feed to the Workshop screen, but in 
general this will not clear the screen. For methods of clearing the screen, see 
the WorkshqD User's Guide for We Lisa . 

103.7 Keyboard Testing and Screen Cursor Control 
103.7.1 The Keypress Function 

Tests the Lisa keyboard to see if it has a character awaiting input. 

Parameter List no parameters. 

Result Type: booleaa 

Keypress returns true if a character has been typed on the Lisa keyboard but 
has not yet been read, or false otherwise. This is done by testing the 
typeahead queue; if the queue is empty, keypress is false, otherwise it is true. 

10.3.7.2 The Gotoxy Procedure 

Moves the Workshop screen cunor to a specified location on the screen. 

Parameter List- gotoxy()c. y) 

1. X is an expression with an integer value. If x < 0, the value D will be 
used; if x > 79, the value 79 will be used. 

2. y is an expression with an integer value. If y < 0, the value will be 
used; if y > 31, the value 31 will be used. 

Goto)^x. y) moves the cursor to the point (x,y) on the screen. Note that the 
point (0,0) is the upper left comer of the screen. 

ia4 untyped File lA) 

Untyped file I/O operates on an "untyped file," i.e., a variable of type file (no 
component type), H\ untyped file is treated as a sequence of 512-byte blocks; 
the bytes are not type-checked but considered as raw data This can be useful 
for applications where the data need not be interpreted at all during I/O 
operations. 
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The blocks in an untyped file are considered to be numbered sequentially 
starting with 0. The system keeps track of the current block number;M\\% is 
block immediately after the file is opened. Each time a block is read^ the 
current block number is incremented. By default, each I/O operation begins at 
the current block number; however, an arbitrary block number can be specified. 

An untyped file has no file-buffer, and it cannot be used with get, put, or any 
of the text-oriented I/O procedures. It can only be used with reset, rewrite, 
close, eof, and the blodoead and blockwrite functions described below. 

To use untyped file I/O, an untyped file is opened with reset or rewrite, and 
the blockread and blockwrite functions are used for input and output 

10.4.1 The Blockread Function 

Reads one or more 512-byte blocks of data from an untyped file to a program 
variable, and returns the number of blocks read. 

Result Type: Integer 

Parameter List- blockread(f, databuf, count [^ blocknum]) 

1. f is a variable-reference that refers to a variable of type file. The file 
rrajst be open. 

2. databuf is a variable-reference that refers to the variable into which the 
blocks of data will be read. The size and type of this variable are not 
checked; if it is not large enough to hold the data, other program data 
may be overwritten and the results are unpredictable. 

3. count is an expression with an Integer value. It specifies the maximum 
number of blocks to be transferred. Blockread will read as many blocks 
as it can, up to this limit. 

4. blocknum (may be omitted) is an expression with an integer value. It 
specifies the starting block number for the transfer. If it is omitted, the 
transfer begins with the current block. Thus the transfers are sequential 
if the blocknumber parameter is never used; if a blocknumber parameter 
is used, it provides random access to blocks. 

Blockread(f, databuf, count, blocknum) reads blocks from f into databuf, starting 
at block blocknum. Count is the maximum nurrtoer of blocks read; if the 
end-of-file is encountered before count blocks are read, the transfer ends at 
that point. The value returned is the number of blocks sctually read. 

If the last block in the file was read, the current block number is unspecified 
and eof(f) is true. Otherwise, eof(f) is false and the current block number is 
advanced to the block after the last block that was read. 
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ia4.2 TTie BlockwritB Function 

Writes one or more 512-byte blocks of data from a program variable to an 
untyped file, and returns the nunnber of blocks written. 

Result Type: integer 

Parameter List- dlockwrite(f^ databuf, count [, blocknum]) 

1. f is a variable-reference that refers to a variable of type file. The file 
must be open. 

2. databuf is a variable-reference that refers to the variable from which the 
blocks of data will be written. The size and type of this variable are not 
checked. 

3. count is an expression with an Integer value. It specifies the maximum 
number of blocks to be transferred. Blockwrite will write as many blocks 
as it can, up to this limit. 

4. blocknum (may be omitted) is an expression with an integer value. It 
specifies the starting block number for the transfer. If it is omitted, the 
transfer begins with the current block. Thus the transfers are sequential 
if the blocknumber parameter is never used; if a blocknumber parameter 
is used, it provides random access to blocks. 

BIockwrite(f, databuf, count,, blocknum) writes blocks into f from databuf, 
starting at block blocknum. Count is the maximum number of blocks written; 
if disk space runs out before count blocks are written, the transfer ends at 
that point. The value returned is the number of blocks actually written. 

If disk space ran out, the current block number is unspecified. Otherwise, the 
current block number is advanced to the block after the last block that was 
written. 

NOTE 

Unlike Apple 11 and Apple III Pascal, this Pascal does not allow 
blockwrite to write a block at a position beyond the first position after 
the current end of the file. In other words, you cannot create a block 
file with gaps in it. 
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standard Procedures and 
Functions 

This chapter describes all the standard C't)uilt-in'7 procedures and functions in 
Pascal on the Lisa^ except for the I/O procedures and functions described in 
Chapter 10. 

Standard procedures and functions are predeclared. Since all predeclared 
entities act as if they were declared in a block surrounding the program, no 
conflict arises from a declaration that redefines the same identifier within the 
program. 

NOTE 

Standard procedures and functions cannot be used as actual procedural 
and functional parameters. 

This chapter uses a modified BNF notation, instead of syntax diagrams, to 
Indicate the syntax of actual-parameter-lists for standard procedures and 
functions. The notation is explained at the beginning of Chapter 10. 

11.1 Exit and Halt Procedures 

11.1.1 The Exit Procedure 

Exits immediately from a specified procedure or function, or from the main 
progranrt. 

Parameter UsL' exit (id) 

1. id is the identifier of a procedure or function, or of the main program. If 
id is an identifier defined in the program, it must be in the scope of the 
exit call. Note that this is more restricted than UCSD Pascal. 

ExitOd) causes an immediate exit from la Essentially, it causes a jump to the 
end of id. 

NOTE 

The halt procedure (see below) can be used to exit Vne main program 
from a unit without knowing the main program's identifier. 

11.1.2 The Halt Pnxjedure 

Exits immediately from the main program. 

Parameter List: no parameters 

Halt causes an immediate exit from the main program. 

11.2 Dynamic Allocation Procedures 

These procedures are used to manage the heafi a memory area that is 
unallocated when the program starts running. The procedure new is used for 
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all allocation of heap space by the program. The mark and release procedures 
are used together to deallocate heap space^ and the heapresult function is used 
to return the status of the last preceding dynamic allocation operation.. 

11.Z1 The New Procedure 

Allocates a new dynamic variable and sets a pointer variable to point to it 

Parameter Ust' nei(p [^ tl^ ... t/?]) 

1. p is a variable-reference that refers to a variable of any pointer-type. 
This is a variable parameter. 

2. tl, ... t/7are constants, used only when allocating a variable of 
record-type with variants (see below). 

New(p) allocates a new variable of the base-type of p, and makes p point to it. 
The variable can be referenced as p". Successive calls to new allocate 
contiguous areas. 

If the heap does not contain enough free space to allocate the new variable, p 
is set to nil and a subsequent call to the heapresult function will return a 
non-zero result 

If the base-type of p is a record-type with variants, new(p) allocates enough 
space to allow for the largest variant. The form 

ne«(p^ tl, ...t/7) 

allocates a variable with space for the variants specified by the tag values tl, 
... t/7 (instead of enough space for the largest variants). The tag values must 
be constants. They must be listed contiguously and in the order of their 
declaration. The tag values are not assigned to the tag-fields by this 
procedure. 

Trailing tag values can be omitted. The space allocated allows for the largest 
variants for all tag-values that are not specified. 

WAR^41NG 

When a record variable is dynamically allocated with e)qDlicit tag values 
as shown above, you should not make assignments to any fields of 
variants that are not selected by the tag values. Also, you should not 
assign an entire record to this record. If you do either of these things, 
other data can be overwritten without any error being detected at 
compile time. 
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\\23. The Heapresiat Function 

Returns the status of the most recent dynsmlc allocation operation. 

Result Type: integer 

Parameter List- no parameters 

HeapiBsult returns an integer code that reflects the status of the most recent 
call on new, maik, release, or memavail. The codes are given in the Workstiop 
User's Guide; note that the code for a successful operation is 0. 

11J2.3 The Mark Procedure 

Sets a pointer to a heap area 

Parameter List- mark(p) 

1. p is a variable-reference that refers to a variable of any pointer-type. 
This is a variable parameter. 

Maitc(p) causes the pointer p to point to the lowest free area in the heap. The 
next call to new will allocate space beginning at the bottom of this area, and 
then p will be a pointer to this space. The pointer p is also placed on a 
stack-like list for subsequent use with the release procedure (see below). 

11.2.4 The Release Pnxiedure 

Deallocates all variables in a marked heap area 

Parameter List release(p) 

1. p is a variable-reference that refers to a pointer variable. It rmist be a 
pointer that was previously set with the mark procedure. The pointer p 
must be on the list created by the mark procedure; otherwise an error 
occun. 

Release(p) removes pointers from the list, back to and including the pointer p. 
The heap areas pointed to by these pointers are deallocated. In other words, 
release(jp) deallocates all areas allocated since the the pointer p was passed to 
the mark procedure. 

1L23 The Memavail Function 

Returns the maximum possible amount of available memory. 

Result Type: longint 

Parameter List- no parameters 

Memavail returns the maximum number of words (not bytes) of heap and stack 
space that could ever be available to the program, allowing for possible 
automatic expansion of the program's data segment. Note that the result of 
memavail can change over time even if the program does not allocate any 
heap space, because of activities by the operating system or other processes in 
the system. 
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113 Transfer Functions 

■Rie procedures pack and unpack, described by Jensen and Wirth, are not 
supported. 

11.3.1 TTie Trunc Function 

Converts a real value to a longint value. 

Result Type: longint 

Parameter List: trunc(x) 

1. X is an expression with a value of type real. 

Trunc()0 returns a longint result that is the value of x rounded to the largest 
whole number that is between and x (inclusive). 

113.2 The Round Function 

Converts a real value to a longint value. 

Result Type: longint 

Par&TTeter List round(x) 

1. x is an expression with a value of type real. 

Round(x) returns a longint result that is the value of x rounded to the nearest 
whole number. If x is exactly halfway between two whole numbers, the result 
is the whole number with the greatest absolute magnitude. 

1133 The Qrd4 Function 

Converts an ordinal-type or pointer-type value to type longint 

Result Type: longint 

Parameter List: ord4(x) 

1. X is an expression with a value of ordinal-type or pointer-type. 

Ord4(x) returns the value of x, converted to type longint If x is of type 
longint the result is the same as x. 

If x is of pointer-type, the result is the corresponding physical address, of type 
longint 

If x is of type integer, the result is the same numerical value represented by y, 
but of type longint This is useful in arithmetic expressions. For example, 
consider the expression 

abc*xyz 

where both abc and xyz are of type integer. By the rules given in Section 
3.1.1.2, the result of this multiplication is of type integer (16 bits). If the 
mathematical product of abc and xyz cannot be represented in 16 bits, the 
result is the low-order 16 bits. To avoid this, the expression can be written as 

ord4(abc)*xyz 
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This expression causes 32-bit arithmetic to be used, and the result is a 32-bit 
Ifxigint value. 

If X is of an ordinal-type other than integer or longint, the numerical value of 
the result is the ordinal nurT*)er determined by mapping the values of the type 
onto consecutive non-negative integers starting at zero. 

113.4 The Pointer Function 

Converts an integer or longint value to pointer-type. 

Result Type: pointer 

Parameter List: pointer(x) 

1. x is an expression with a value of type integer or longint 

Pointei(x) returns a pointer value that corresponds to the physical address x. 
This pointer is of the same type as nil and is assignment-compatible with any 
pointer-type. 

11.4 Arithmetic Functions 

In general^ any real result returned by an arithmetic function is an approx- 
imation. There are two exceptions to this: the result of the abs function is 
exact, and the result of the pwroften function is exact when the parameter n 
is in the range < n < 10. 

11.4.1 The Odd Function 

Tests whether a whole-number value is odd. 

Result Type: boolean 
Parameter List odd(x) 

1. x is an expression with a value of type integer or longint 
Odd(x) returns true if x is odd; otherwise it yields false. 

11.4.2 The Abs Function 

Returns the absolute value of a numeric value. 

Result Type: same as parameter 
Parameter List: abs(x) 

1. X is an expression with a value of type real, integer, or longint 
Abs(x) returns the absolute value of x. 
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1L43 The ScjT Function 

Returns the square of a numeric value. 

Result Type: depends on parameter (see below) 

Parameter List- sc|r(x) 

1. X is an expression with a value of type real, integer^ or longint 

Sqi(x) returns the square of x. If x is of type real, the result is real; if x is of 
type longint the result is longint; and if x is of type integer, the result may be 
either integer or longint 

If x is of type real and floating-point overflow occurs, the result is +«>. 

11A4 The Sin Function 

Returns the sine of a numeric value. 

Result Type: real 

Parameter List' sin(x) 

1. x is an expression with a value of type real, integer, or longint This 
value is assumed to represent an angle in radians. 

Sin(x) returns the sine of x. If x is infinite, a diagnostic NaN is produced and 
the invalid operation signal is set (see Appendix D). 

11.43 The Cos Function 

Returns the cosine of a numeric value. 

Result Type: real 

Parameter List- cos(x) 

1. X is an expression with a value of type leat integer, or longint This 
value is assumed to represent an angle in radians. 

Cos(x) returns the cosine of x If x is infinite, a diagnostic NaN is produced 
and the invalid operation signal is set (see Appendix D). 

11.4.6 The Exp Function 

Returns the exponential of a numeric value. 

Result Type: real 

Par&TWter List- exp(x) 

1. X is an expression with a value of type real, integer, or longint All 
possible values are valid. 

Exp(x) returns the value of e^, where e is the base of the natural logarithms. 
If floating-point overflow occurs, the result is +«». 
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11A7 The Ln Function 

Returns the natural logarithm of a numeric value. 

Result Type: real 

Parameter List- ln(x) 

1. X is an expression with a value of type real^ integer, or longinL All 
non-negative values are valid; negative values are Invalid. 

If X is non-negative, ln(x) returns the natural logarithm (log^* ) of x. 

If X is negative, a diagnostic NaN is produced and the Invalid Operation signal 
is set (see Appendix D). 

ILOwS The Sqrt Function 

Returns the square root of a numeric value. 

Result Type: real 

Parameter List' sc|rt(x) 

1. X is an expression with a value of type real^ integer, or longlnt All 
non-negative values are valid; negative values are Invalid. 

If X is non-negative, sqrt(x) returns the positive square root of x 

If X is negative, a diagnostic NaN is produced and the Invalid Operation signal 
is set (see Appendix D). 

IIAS The Arctan Function 

Returns the arctangent of a numeric value. 

Result Type: real 

Parameter List arctan(x) 

1. X is an expression with a value of type real, integer, or longint All 
numeric values are valid, including ±» 

Arctan(x) returns the principal value, in radians, of the arctangent of x 

IIAIO The Pwroften Function 

Returns a specified power of 10. 

Result Type: real 
Parameter List' pi»roften(n) 
1. n is an expression with a value of type integer. 

If -45 < n < 38, then pwroflen(n) returns lO". The result is mathematically 
exact f or < n < 10. If n < -46, the result is 0; if n > 39, the result is +«.. 
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113 Ordinal Functions 
115.1 The Qrd Function 

Returns the ordinal number of an ordinal-type or pointer-type value. 

Result Type: integer or longint 

Parameter List' ord(x) 

1. X is an expression with a value of ordinal-type or pointer-type. 

If X is of type integer or longint the result is the same as x 

If X is of pointer-type, the result is the corresponding physical address, of type 
longint 

If X is of another ordinal-type, the result is the ordinal number determined by 
mapping the values of the type onto consecutive non-negative whole numbers 
starting at zero. 

For a parameter of type char, the result is the corresponding ASCII code. For 
a parameter of type boolean, 

ord(false) returns 
ord(true) returns l 

11.5^ TTie Chr Function 

Returns the char value corresponding to a whole-number value. 

Result Type: char (but see below) 

Parameter List' chr(x) 

1. X is an expression with an integer or longint value. 

Chr(x) returns the char value whose ordinal number (i.e., its ASCII code) is x, if 
X is in the range a.255. If x is not in the range a.255, the value returned is 
not within the range of the type char, and any attempt to assign it to a 
variable of type char will cause an error. 

For any char value ch, the following is true: 

chr(ord(ch)) = ch 

115.3 "me Succ Function 

Returns the successor of a value of ordinal-type. 

Result Type: same as parameter (but see below) 

Parameter List' succ(x) 

1. X is an expression with a value of ordinal-type. 

Succ(x) returns the successor of x if such a value exists according to the 
inherent ordering of values in the type of x 
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If X is the last value in the type of x, it has no successor. In this case the 
value returned is not within the range of the type of x. and any attempt to 
assign it to a variable of this type will cause unspecified results. 

113.4 The Pred Function 

Returns the predecessor of a value of ordinal-type. 

Result Type: same as parameter (but see below) 

Parameter List: pred(x) 

1. x is an expression with a value of ordinal-type. 

Pred(x) returns the predecessor of x, if such a value exists according to the 
inherent ordering of values in the type of x 

If X is the first value in the type of >c it has no predecessor. In this case the 
value returned is not within the range of the type of x, and any attempt to 
assign it to a variable of this type will cause unspecified results. 

11.6 String Procedures and Functions 

The string procedures and functions do not accept packed array of char 
parameters^ and they do not accept indexed string parameters. 

11.6.1 The Length Function 

Returns the current length of a value of string-type. 

Result Type: integer 
Parameter List Iength(str) 

1. str is an expression with a value of string-type. 
Length(str) returns the current length of str. 

1L6.2 The Pos Function 

Searches a string for the first occurrence of a specified substring. 

Result Type: integer 

Parameter List posCsudstr, str) 

1. substr is an expression with a value of string-type. 

2. str is an expression with a value of string-type. 

Pos(substr^ str) searches for substr within str, and returns an integer value that 
is the index of the first character of substr within str. 

If substr is not found, pos(substr, str) returns zero. 
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11A3 TTie Concat Function 

Takes a sequence of strings and concatenates tnem. 

Result Type: string-type 

Parameter List concat(strl {, str2^ ... str/?]) 

• Each parameter is an expression with a value of string-type. Any practical 
numtjer of parameters may be passed. 

Concat(strl, ~.^ str/?) concatenates all the parameters in the order in which 
they are written, and returns the concatenated string. Note that the number 
of characters in the result cannot exceed 255. 

11.6.4 The Copy Function 

Returns a substring of specified length, taken from a specified position within 
a string. 

Result Type: string-type 

Parameter List- copy (source, index, count) 

1. source is an expression with a value of string-type. 

2. index is an expression with an integer value. 

3. count is an expression with an integer value. 

Copy(source, index, count) returns a string containing count characters from 
source, beginning at sourc8[index]. 

11.63 The Delete Procedure 

Deletes a substring of specified length from a specified position within the 
value of a string variable. 

Parameter List- delete(dest, index, count) 

1. dest is a variable-reference that refers to a variable of string-type. This 
is a variable parameter. 

2. index is an expression with an integer value. 

3. count is an expression with an integer value. 

Delete(dest, index, count) removes txjunt characters from the value of dest, 
beginning at dest[index]. 

11.6.6 TTie Insert Procedure 

Inserts a substring into the value of a string variable, at a specified position. 

Parameter List' insert (source^ dest, index) 

1. source is an expression with a value of string-type. 

2. dest is a variable-reference that refers to a variable of string-type. This 
Is a variable parameter. 

3. index Is an expression with an integer value. 
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Insert(source, des^ index) inserts source into dest The first character of 
source becomes dest[index]. 

11.7 Byte-Oriented Procedures and Functions 

These features allow a program to treat a program variable as a sequence of 
bytes^ without regard to data types. 

NOTE 

The sizeof function (described in Section 11.7.3, below) can be used to 
determine the number of bytes in a variable. 

These procedures do no type-checking on their source or dest actual- 
parameters. However, since these are variable parameters they cannot be 
Indexed if they are packed or if they are of string-type. If an unpacked 
'tiyte array" is desired, then a variable of the type 

array [lo..hi] of -128.. 127 

should be used for source or dest The elements in an array of this type are 
stored in contiguous bytes, and, since it is unpacked, an array of this type can 
be used with an index as an actual-parameter for these routines. 

IMPLEMENTATION NOTE 

Currently, an array with elements of the type a.255 or the type char 
has its elements stored in words, not bytes. 

11.7.1 The Movelefl Procedure 

Copies a specified number of contiguous bytes from a source rang& to a 
ctBstlnatim r&'^ (starting at the lowest address). 

Parameter List- inoveleft( source, dest, count) 

1. source is a variable-reference that refers to a variable of any type 
except a file-type or a structured-type that contains a file-type. This is 
a variable parameter. The first byte allocated to source (lowest address 
within source) is the first byte of the source range. 

2. dest is a variable-reference that refers to a variable of any type except 
a file-type or a structured-type that contains a file-type. This is a 
variable parameter. The first byte allocated to dest (lowest address 
within dest) is the first byte of the destination range. 

3. count is an expression with an integer value. The source range and the 
destination range are each count bytes long, 

Moveleft(source, dest, count) copies count bytes from the source range to the 
destination range. 
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Moveleft starts from the "left" end of the source range (lowest address). It 
proceeds to the "right" (higher addresses), copying bytes Into the destination 
range, starting at the lowest address of the destination range. 

The count paranneter Is not range-checked. 

11.7.2 The Moveright Procedure 

Moveright is exactly like moveleft (see above), except that it starts from the 
"right" end of the source range (highest address). It proceeds to the "left" 
(lower addresses), copying bytes into the destination range, starting at the 
highest address of the destination range. 

The reason for having both moveleft and moveright is that the source and 
destination ranges may overlap. If they overlap, the order In which bytes are 
moved is critical: each byte must be moved before it gets overwritten t^"^ 
another byte. 

11.7.3 The Sizeof Function 

Returns the number of bytes occupied by a specified variable, or by any 
variable of a specified type. 

Result Type: integer 

Parameter List: sizeof (id) 

1. id is either a variable-identifier or a type-identifier. It must not refer to 
a file-type or a structured-type that contains a file-type, or to a 
variable of such a type. 

Sizeof(id) returns the number of bytes occupied by id, if id is a variable- 
identifier; if id is a type-identifier, it returns the number of bytes occupied by 
any variable of type id. 

11.8 Packed Array of Char Procedures and Functions 

NOTE 

These routines operate only on packed arrays of char. The packed 
arrays of char cannot be subscripted; the operations always begin at the 
first character in a packed array of char. 

11.8.1 TTie Scaneq Function 

Searches a packed array of char for the first occurrence of a specified 
character. 

Result Type: integer 

Parameter UsL' scaneq(limit, ch, paoc) 

1. limit is an expression with a value of type integer or longint It is 
truncated to 16 bits, and is not range-checked. 

2. ch is an expression with a value of type char. 
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3. paoc is an expression with a value of type packed array of char. This is 
a variable parameter. 

ScaneqOilmit^ ch, paoc) scans paoc^ looking for the first occurrence of cTi The 
scan begins with the fint character in paoc. If the character is not found 
within limit characters from the beginning of paoc^ the value returned is equal 
to limit Otherwise, the value returned is the number of characters scanned 
before ch was found. 

11A2 The Scanne Function 

This function is exactly like scaneq, except that it searches for a character 
that does not match the ch parameter. 

11A3 The Fiiichar Procedure 

Fills a specified number of characters in a packed array of char with a 
specified character. 

Parameter List- fillchar(paoc, count, ch) 

1. paoc is an expression with a value of type packed array of char. This is 
a variable parameter. 

2. count is an expression with a value of type integer or longint It is 
truncated to 16 bits, and is not range-checked. 

3. ch is an expression with a value of type char. 

Fillchai(paoc, count, ch) writes the value of ch into count contiguous bytes of 
memory, starting at the first byte of paoc. 

Since the count parameter is not range-checked, it is possible to write Into 
memory outside of paoc, with unspecified results. 
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The Pascal compiler translates Pascal source text to an intemnedlate code^ and 
the code generator translates the intermediate code to MC68000 object code. 
Instructions for operating the compiler and code generator are given In the 
WorkstTOp User's Guide for the Lisa 

12.1 Compiler Commands 

A compiler command is a text construction^ embedded in source text^ that 
controls compiler operation. Every compiler command is written within 
comment delimiters, {...[ or (*...*> Every compiler command begins with the $ 
character, which must be the first character inside the comment delimiters. 

In this manual, compiler commands are shown in upper case to help distinguish 
them from Pascal program text; however, upper and lower case are inter- 
changeable in compiler commands just as they are In Pascal program text. 

The following compiler commands are available: 

IhPUT FILE CONTROL 

$1 filename start taking source code from file filename. When the end 
of this file is reached, revert to the previous source file. 
If the filename begins with + or -, there must be a space 
between $1 and the filename (the space is not necessary 
otherwise). 

$U filename Search the file filename for any units subsequently 

specified in the uses-clause. Does not apply to intrinsic- 
units. 

CONTROL OF CODE GENERA TION 

$C+ or $C- Turn code generation on (+) or off (-). This is done on a 
procedure-by-procedure basis. These commands should be 
written between procedures; results are unspecified if they 
are written inside procedures. The default Is *C+. 

$C1V* or $0V- Turn integer overflow checking on (♦) or off (-). Overflow 
checking Is done after all integer add, subtract, 16-blt 
multiply, divide, negate, abs, and 16-bit square operations, 
and after 32 to 16 bit conversions. The default Is $0V-. 

$R* or $R- Turn range checking on (+) or off (-). At present, range 
checking Is done in assignment statements and array 
indexes and for string value parameten. No range 
checking is done for type longint The default is $R+ 
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$S segname Start putting code modules into segment segname. me 

default segment name is a string of blanks to designate the 
"blank segnnent;' in which the main program and all built-in 
support code are always linked. All other code can be 
placed Into any segment 

$X+ or $X- Turn automatic run-time stack expansion on (+) or off (-> 
The default Is $x*. 

NOTE 

Compiler directives that affect code generation take effect when the 
end of the Pascal statement in which they are embedded is reached. If 
the same directive is specified more than once in a statement, the last 
setting is used. A tricky case of this Is: 

begin 

3 := foo; 

{««-} 

1 := i»2 

end 

Since the second assignment does not end with a semicolon, and 
actually ends when the end Is encountered, range checking will not be 
turned off for that statement. 



DEBUGGING 

$D* or $D- Turn the generation of procedure names in object code on 
(♦) or off (-). These commands should be written between 
procedures; results are unspecified If they are written 
Inside procedures. The default Is $D+. 

CONDITIONS COMPILATION 

$DECL list (see Section 12.2 below). 

$ELSEC (see Section 12.2 below). 

$ENDC (see section 12.2 below). 

$IFC (see Section 12.2 below). 

$SETC (see Section 12.2 below). 
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LISTING CONTROL 

*E filename Start making a listing of compiler errors as they are 

encountered. Analogous to $L filename (see below). The 
default Is no error listing. 

$L filename Start listing the compilation on file filename. If a listing 
Is being made already, that file is closed and saved prior to 
opening the new file. The default is no listing. If the 
filename begins with + or -, there must be a space between 
$L and the filename (the space is not necessary otherwise). 

$L* or $L- The first ♦or - following the $L turns the source listing on 
(♦) or Off (-) without changing the list file. You must 
specify the listing file before using $L+. The default is 
IL+, but no listing is produced if no listing file has been 
specified. 

12.2 Condltltxiai compilation 

Conditional compilation is controlled by the $IFC, SELSEC, and $ENDC 
commands, which are used to bracket sections of source text. Whether a 
particular bracketed section of a program is compiled depends on the boolean 
value of a compUe-time expression which can contain compile-time variables 

12.2.1 Complle-Time v^ables and the $DECL Command 

Compile-time variables are completely independent of program variables; even 
if a compile-time variable and a program variable have the same identifier, 
they can never be confused by the compiler. 

A compile-time variable is declared when it appears in the identifier-list of a 
$DECL command. 

Example of conpile-time vari^le declaration: 

{SOECL LIBVERSIOi PROGVERSION} 

This declares LIBVERSION and PROGVERSION as complle-tlme variables. 
Notice that no types are specified. 

Note the following points about compile-time variables: 

• Complle-tlme variables have no types, although their values do. The only 
possible types are integer and boolean. 

• All complle-tlme variables should be declared before the end of the 
varlable-declaratlon-part of the main program. In other words a $OECL 
command that declares a new complle-tlme variable must precede the 
main program's procedure and function declarations (if any). The new 
compile-time variable is then known throughout the remainder of the 
compilation. 

• At any point in the program, a complle-tlme variable can have a new 
value assigned to It by a $SETC command. 
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12.22. The $SETC comrnand 

The $SETC command has the form 

{$SETC ID := EXPR} 

or 

{$SETC ID = EXPR} 

Where ID is the identifier of a complle-tlme variable and EXPR is a compile- 
tlme expression. EXPR is evaluated immediately. The value of EXPR is 
assigned to ID. 

Example of assignment to complle-tlme variable: 

{$SETC LIBVERSION := 5} 

This assigns the value 5 to the compile-time variable LIBVERSION. 

12.2.3 Compile-Time Expressions 

complle-tlme expressions appear In the $SETC command and In the $IFC 
connmand. A compile-time expression is evaluated by the compiler as soon as 
it is encountered In the text. 

The only operands allowed in a compile-tlme expression are: 

• Compile-time variables 

• Constants of the types Integer and txx3lean. (These are also the only 
possible types for results of compile-time expressions.) 

All Pascal operators are allowed except as follows: 

• The in operator Is not allowed. 

• The • operator is not allowed. 

• The / operator is automatically replaced by div. 

12.2.4 The $FC^ $ELSEC, and $ENDC Commands 

The $ELSEC and $ENDC commands take no arguments. The $FC command has 
the form 

{$IFC EXPR} 

Where EXPR is a compile-tlme expression with a txMlean value. 

These three commands form constructions similar to the Pascal if-statement, 
except that the $ENDC command is always needed at the end of the $!FC 
construction. $ELSEC Is optional. 
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Example of conaiUonally compllecf cocfe: 

{$IFC PROGVERSION >= LIBVERSION) 

k := kvallCdata+indat); 
{«ELSEC} 

k := kval2(data+qf)lndat " ); 
{$ENDC} 

wlteln(k) 

If the value of PRCGVERSION Is greater than or equal to the value of 
LIBVERSION, then the statement k:-kvall(data+lnclat) Is compiled, and the 
statement k:-kval2(data-KpinGiat") Is skipped. 

But if the value of PROGVERSION is less than the value of LIBVERSION, then 
the first statement is skipped and the second statement is compiled. 

In either case, the wilteln(k) statement is compiled because the conditional 
construction ends with the $ENDC command. 

$IFC constructions can be nested within each other to 10 levels. Every $IFC 
must have a matching $ENDC. 

When the compiler is skipping, all commands in the skipped text are ignored 
except the following: 

$ELSEC 

$ENDC 

$IFC (so that $ENDC's can be matched properly) 

All program text is ignored during skipping. If a listing is produced, each 
source line that is skipped is marked with the letter S as its "lex level." 

12.3 pptlmization of If-Statements 

When the compiler finds an if-statement controlled by a boolean constant, it 
may be unnecessary to compile the then part or the else part. For example, 
given the declarations 

const always = true,- 
never = false; 

then the statement 

If never then statement 

will not be compiled at all. In the statement 

if never then statementl 
else statementz 

"statementl" is not compiled; only "statementz" is compiled. 
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Similarly^ in the statement 

if always then statementi 
else statementz 

only "statementl" Is complied. 

The interaction between this optimization and conditional compilation can be 
seen from the following program: 

program Foo; 

{$SETC FLAG := FALSE} 

const pi = 3.1415926; 

Size = 512; 
{$IFC FLAG} 

debug = false; (a boolean constant^ if FLAG=true} 

{$ENDG} 

var i, j^k^l^ntn: integer; 
{$IFC NOT FLAG} 

debug: boolean; {a boolean variable^ if FLAG=false} 
{$ENDC} 

{$IFC NOT FLAG} 
procedure whatmode; 

begin 
{interactive procedure to set global boolean variable, debug} 

end; 
{$ENDC} 

begin {main} 
{$IFC NOT FLAG} 

whatmode; 
{«ENDC} 

if debug then begin 

statementl 
end 
else begin 

statement2 
end 

end. 

The way this is compiled depends on the compile-time variable FLAG. If 
F1.AG is false, then debug is a boolean variable and the whatmode procedure 
is compiled and called at the beginning of the main program. The if debug 
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statBfnenl is controlled by a txnlean variable and all of it is compiled, in the 
usual manner. 

But if the value of FLAG is changed to tnie^ then debug is a constant with 
the value false^ and whatmode is neither compiled nor called. The if debug 
statement is controlled by a constant so only its else part, "statement2", is 
conpiled. 

12.4 Optimization of While-Statements and Repeat-Statements 

A While-Statement or repeat-statement controlled by a boolean constant does 
not generate any conditional branches. 

12.5 Efficiency of Case-Statements 

A sparse or small case-statement will generate smaller and faster code than 
the corresponding sequence of if-statements. 
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Comparison to Apple II and Apple III 

Pascal 



This appendix contains lists of the nrtajor differences between the Pascal 
language on the Lisa and the Pascal implemented on the Apple 11 and Apple 111. 
Please note that these lists are not exhaustive. 

A.1 Extensions 

The following features have been added on the Lisa: 

• ® Operator— returns the pointer to its operand (see Section 5.1.6). 

• Heapresult pointer^ and ord4 functions (see Sections 11.2.2^ 11.3.3, and 
11.3.4). 

• Keypress function built into the language, with same effect as the keypress 
function in the applestuff unit of Apple II and Apple III Pascal (see Section 
10.3.7.1). 

• Hexadecimal constants (see Section 1.4). 

• Otherwise-clause in case-statement (same as Apple III Pascal; see Section 
6.2.2.2). 

" Global goto-statement (see Section 6.1.3). 

• A file of char type that is distinct from the text type (see Sections 3.2.4 
and 10.3). 

• Numerous compiler commands (see Section 12.1X 

• Procedural and functional parameters (see Sections 7.3.3 and 7.3.4). 

• Stronger type-checking (see sections 3.4 and 7.3.5). 

• QuickDraw graphics and hardware interface, including mouse control (see 
Appendixes E and F). 

A.2 Deletions 

The following features are not included on the Lisa: 

• Turtlegraptilcs, applestuff, and other standard units of Apple 11 and Apple 
III Pascal. 

• Interactive type (not needed, as the 1/0 procedures will do the right thing 
with a file of type text if it Is opened on a character device). 

• Keyboard file— same effect can be obtained by opening a file of type text 
on the device -KEYBOARD (see Section 10,3). 
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Unit (device-oriented) I/O procedures^ such as UNITBUSY. 

Recognition of the ETX character (control-C) to mean "end of file" in input 
from a character device. 

"Long integer*" data type, with length attribute in declaration. Replaced by 
the longint type (see Section 3.1.1.2). 

"Initialization" code In a unit (see Chapter 9). 

The ability to create new intrinsic-units and install them In the system 
(see Chapter 9). 

Reset procedure without an external file tltle^ for use on a file that is 
already open (see Section 10.1.1). To obtain the same effect^ close the file 
and reopen it. 

Tneesearch. 

Bytestrearo, woidstream (data types in Apple III Pascal). 

Exlt(program)~The exitpdentifler) form works, and the identifier can be the 
program-identifier. Halt can also be used for orderly exit from a program 
(see Sectlonll.l)L 

Extended comparisons (see Section 5.1.5). 

Scan function. Replaced by scaneq and scanne (see Section 11.8). 

Str function. 

Bit-wise boolean operations 

Segment keyword for procedures and functions. Use the $S command 
instead (see Section 12.1). 

The following compiler commands (see Section 12.1> 

• *!♦ and *[- (no automatic I/O checking; program must use ioresiat 
function) 

• $G ($G+ is the assumption on the Lisa) 

• $N and $R (for resident code segments) 
•$P 

• $S+ and $S** for swapping 

• $U+ and $U- (for User Program) 

•$V 

In general, do not assume that a compiler command used in Apple II or 
Apple III Pascal is valid on the Lisa Furthermore, do not assume that an 
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Apple II or Apple III Pascal compiler command Is "harmless" on the Lisa, as 
it may be implemented with a different meaning. 

A.3 Other Differences 

The following features of Pascal on the Lisa are different from the 
corresponding features of Apple II and Apple 111 Pascal: 

• Size of all strings must be explicitly declared (see Section 3.1.1.6). 

• Mod and dlv~Pascal on the Lisa truncates toward (see Section 5.1.2). 

• /^le II and Apple III Pascal ignore underscores; Pascal on the Lisa does 
not They are legal characters in identifiers (see section 1.2). 

• A goto-statement cannot refer to a case-constant in Pascal on the Lisa 
(see Section 6.1.3). 

• A program must begin with the word program in Pascal on the Lisa (see 
Chapter 8). 

• Tninc is different (see Section 11.3.1). 

• wnte(b) where b is a boolean will write either ' TRUE' or 'FALSE' in Pascal 
on the Lisa (see Section 10.3.3). 

• Whether a file is a textfile does not depend on whether its name ends with 
".TEXT" when it is created. Instead, any external file opened with a file 
variable of type text is treated as a textfile, while a file opened with a 
file variable of type file of char is not; it is treated as a "datafile," l.e. a 
straight file of records which are of type char (see Sections 3.2.4 and 10.2). 

• Get put, and the contents of the file buffer variable are not supported on 
files of type text Use only the text-oriented I/O procedures with textfiles. 

• Eoln and eof functions on files of type text work as they do on interactive 
files in Apple II and Apple III Pascal. 

• Pascal on the Lisa does not let you pass an element of a packed variable as 
a variable parameter (see Sections 7.3.2, 11.7, and 11.8). 

• Limits on sets are different (see Section 3.2.3). 

• The control variable of a for-statement must be a local variable (see 
Section 6.2.3.3X 

• In a write or wrlteln call, the default field lengths for integer and real 
values are 8 and 12 respectively (see Section 10.3.3). 



A-3 



Appendix B 
Known Anomalies in the Compiler 



This ^jpesTdix describes the krrawn ancMTialies in the current inplementation of 
the compiler. 

B.1 Scope of Declared Constants 

Consider the following program: 

program cscopel; 
const ten=10; 

procedure p; 
const ten»ten; {THIS SHOULD BE AN ERROR} 
begin 

inriteln(ten) 
end; 

begin 

P 
end. 

The constaffit declaration in procedure p should cause a compiler error^ because 
it is illegal to use an identifier within its own declaration (except for pointer 
identifiers^ However, the error is not detected by the conpiler. The effect is 
that the value of the global constant ten is used in defining the local constant 
terv and the writein statement writes "10". 

A more serious arromaly of the sane kind is illustrated by the following 
prc^ram: 

program cscape2; 
const red=l; violet=2; 

procedure q; 
type array Type=array [red.. violet] of integer; 

color = (violet^ blue^ green, yellon, orange, red); 
var arrayVarrarrayType; ccolor; 
begin 
arrayVar[l]:=l; 
c:=red; 

witeln(ord(c)) 
end; 

begin 

q 

end. 
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Within the procedure q, the global constants red and violet are used to define 
an array index type; the effect of aiTa){redu.violet] is equivalent to ana^l^} 
In the declaration of the type color, the constants red and vicdet are locally 
redefined; they are no longer equal to 1 and 2 respectively— instead they are 
constants of type color with ordinalities 5 and respectively. The writeln 
statement writes "5". 

The use of red in tire declaration of the type color should caise a corr^iler 
error but does not 

Consider the statement 

arrayVar[l]:=l; 
If this statement is replaced by 

arrayVar[red] :=1; 

a compiler error will result, as red is now an illegal index value for arrayVar 
—even though arrayVar is of type arraylype and arrayType is defined by 
arra)(refl.violet]. 

To avoid this kirrcl of situatim, avoid redefinition of constant-identifiers in 
enimerated scalar types. 

B.2 Scope of Bese-Types for Pointers 

Consider the following program: 

program pscopel; 

type s«0-.7; 

procedure makecurrent; 
type sptr=*s; 
s=record 
ch:char; 
bool: boolean 
end; 
var current :s; 
ptrs:sptr; 
bi^in 

i l^?W\ iaPi»X ^3/f 

ptrs * : ^current 
end; 

begin 

makecurrent 
end. 

Htere we have a global type z, which is a siisrsHige of integer; we also have a 
local ty|:« s, which is a ra:x}rd-t3^. Within the procedure makecurrent, the 
type sptr is defined as a pointer to a vmiBble of type s. The intention is that 
this should refer to the local type s, defined on the next line of the program; 
unfortmately, however, the corrpiler does not yet know atwxit the local type s 
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and uses the global type s. TTws ptn becomes a pointer to a variable of type 
Q-7 instead of a pointer lo a record. Coroequently the statement 

ptrs := current 

causes a compiler error since ptn* and current are of incompatible types. 

To avoid this kind of situation, re-declare the type s locally before declaring 
the pointer-type sptr trased on s. Alternately, avoid re-declaration of 
identifiers that are used as b^e-types for pointer-types. 
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ai Tokens and Constants C-1 

02 Blocks C-4 

C3 Data Types C-5 

CA V^ables C-9 

C.5 Expressions C-10 

ae Statements C-12 

C.7 PToceduies and Functions C-15 

C.8 Programs C-16 

a9 units C5-17 



Syntax of the Language 



This appendix collects the syntax diagrams found in the main sections of this 
manual. See the Preface for an introduction to syntax diagrams, 

CI Tokens and Constants (see Chapter l) 



letter 



(a) mrotjgtr (z) , (a) tnmugh (z) 



^Ei ^ 



(o) thmugh (i) 



hex-dfaft 



Y» | digit I Y 

W (^ throuah (t) -^ 



identifier 



^ letter 









N 


letter 


^ J 








digit 


d "^ 










\ 


unders 


core 


*-> 



dialt-seQuence 



C 



digit 



T 



hex-diQit-seouence ^ . ^. .. ^ 




V^ ) 
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unsioned-inteaer 




digit-sequence 



hex-dlgit-sequence 



J 



sign 



<E> 




unsigned-real 

— ► digit-sequence -^Y^y-^ digit-sequence 



T 



-^ scale-factor-^ 



scale-h^tor 



•Ke) 




sign 



W 



digit-sequence 



unslgnecf-number 



\^ 



m unsigned-integer 



unsigned-real 



siQned-number 



N^ sign — ' 



unsigned-number 



quoted-sUing-constant 



O 



X. 



string-character 



4l^-J 



O-^ 
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string-character 



any dmr except Qj arCR 



T—^ any drar 
^ 



o-o 



J— 



etuotea-cnaracter-amtant >(Ty ^ string-character | -»0-» 



constant-declaration 



»• Identifier —-»{*) — »■ constant 



constant 


^ » ^ 1^ xf/.f 




A 


"\ /• i^ constant-identiner 


N 




^ sign -^ 












^ 








T^ quoiea smny 


-V 



^ quotea-cnar 
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C^ Blocks (see Chapter 2) 

acfck 



"T 



'^ 



^"^ constant-declaration-part 



r 



""^ type-declaration-part 



label-declaration-part 









^ 






'"^ variable-declaration-part 



^ 






^ procedure-and-function-declaration-part 



^ 



^ statement-part 



£D 



labeJ-cfecIaratlon-part 
<^> 



C 



label 




latjel 



^ digit-sequence 



•O 



cxjnstant-decla/aUon-part 
K^^S) 



I 



constEnt-declaration 



T^ 



tj^-c^laration-part 



■» (^type^ 7 — » type-cteclaratim — «r — ^ 
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variable-cteclaraUon-part 

— KI^ 



c 



variable-declaration 



y^ 



pwceduw-afxt-function-decJaration-part 
T 



XI 



procedure-declaraticMi 



"T 



function-declaration 



statement-part 



compound-statement 



C3 Data Types (see Chapter 5) 



type-declaraUon 



identifier 



X9-H]^pi}--KI> 



tme 



siiTiple-t)pe 



structured-type 



pointer-type 



simple-type 



ordinal-type 



real-type 



* string-type 



"^ 



-^ 



real-type 



^ real-type-identifier 
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ordinal-type 



subrange-type 



enumeraled-type 



■^ 



ordinal-type-identifier 



stilfig-type 

-» (Ttring ) — »(T)'~ H size-attribute | — ►(!)• 



u 



strlng-type-identifler 



T* 



size~attrit3Ute 



^ unsigned-integer 



enurmmtea-tm »(^)-> rte;;iii;i;rh »()>-» 



Identifier-list 



identifier 



Y^w lUBfiiiTier — ^- 



'"^^-^yp^ ^ Y ^^^^i^Dr <^:y- A^ 
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syntax 



stjyctumcf-twe 



^-» ( packed } --^ 






array- type 



7 T 



set-type 



^ 



file-type 



record-type 



structured-type-identifier 



I 



array-type 

—» ( array } -»(r)-y ^ index-type | ---Y^(T)--K^Qr)- ^lype^ 



inaex-type ^ \ pyjirial-type I ► 



recom-type ^ ( ^^^ 



^ field-list -^ 



KW)-^ 




'-JV^J 



fixed-part 



C 



field-declaration 



O 



I 



field-declaration 



identifier-list — ►(T) — » type 
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variant-part 
case. 



\ , -M teg-field-type KgHr*b!griantU- 

^ lclentifier"[ -»(7V ^^^ Q)^ 



taQ-fleld-tms 



ordinal-type-identifier 



variant 



^r-» constant ■ ». ^G^)"^?)""^ — / • »( j) — ► 

I C^ ^ J ^ field-list K 



O 



M-tm-^^(-^^^^(;^y ^ ordlnal-ty^ 



>^/^^ ^ >(jg^ 



^'-^CoT)- ^ type K 



pointer-type ►( ^ base-typ^ 



^ DC 



pointer-type-ictentifier 



— Y ► 



base-type ^ type-ldenUfler 
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CX4 variatdes (see Chapter 4) 



varIai)le-cfecJaiatIon 



identifier-list -»(T)-I» type -»(T) ► 



variable-re^rence 

► 



varladle-identifler 



^ qualifier U— ^ 



uanabJe-ictentifier 



^ ictentifier 



QualWer 






index 



field-designator 



^ 



"^-^ file-buffer-symbol 



^ pointer-odject-symtx)l 



L. 



Index 



<£> 



I 



expression 



O 



r 



(D-* 



fleJcf-cfesj'onator 



O— * 



identifier 



flle-txjffier-symtol 



O 



polnter-obj^t-swntjoj 



<!> 
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as Expressions (see Chapter 5) 

unslaned-constant 






^ 



unsigned-number 



quoted-strlng-conslanl 



constant-identifier 



<^ 



■^ 



Jiw. 



factor 



^ 



^ 



^ 



Vi>^ ' 



variable- reference 



unsigned-constant 



function-call 



set-constructor 



<(>l 



expression 



\^ 



->^not)-» factor 



^ 



^ 
"^ 



^ 



A- 



term 




sJnTDle-ewressJcm 



\ I — ,/ 

^^ sion -^ 



7- — ► term 



^ 
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Syntax 



e)pression 



simple-expression h— r 






simple-expression 



funcUon-cail 

^ 



function-identifier 



Vi 



actual-parameter-list 



tT 



actm-parmeter-mt »(7V ^ actual-parameter h ^-«<)) 



I 



o 



y-nj/-^ 



actual-parameter 






expression 



variable-reference 



-^ 



^ 



procedure-identifier 



^ 



function-identifier 



iw- 



set-constructor 



KCk — 



c 



member-group 



O 



T 



-j<S>^ 



C-ll 
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Syntax 



meniber-awuD 



expression 



^K,"y~ H expression \ ^ 



C.6 Statements (see Chapter 6) 

statement 



^ label [ -»(rK r^ 



J 



simple-statement 



structured-statement 



77 



label 



¥ digit-sequence ► 



sirwle-statement 



assignment-statement 



procechjre-statement 



■> 



goto-statement 



\ ^ 



^ssj§fnf}^^7t~st3tef)7ent 



W 



variable-reference 



function-identifier 



cw 



vE) — ^ expression 



procec/uie-statement 

► 



procedure-identifier 



t;i 



actual -parameter-list 



TT 



Qoto-statement » (ji;^)_»[l^ 
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Syntax 



stnictured-statement 




^ 


compound-statement 










\ 




•\ 


I. 






conditional-statement 


J "^ 






repetitive-statement 


J ^ 








ite 




^ 


wim-statcment 









corrpomchstatement 
» Cte9in> 



j- ^ statement { — k — ► 



<^ 



O 



concUUonal-statement 



v\ 



If-statement 



case-statement 



If-statement 



<e)-^ 



ejqpression 



^ ^then 



D 



then)--» statement 



elseH^ statement 



l7 



case-statement » ( ^^)-»| expression 



Of 





otherwise-clause 



O-*^ 



case 



7— ► constant — v K!i)~^ statement 

I r\- ) 



O 



otherwl^-clause 



*(7y- ^ otherwise ^ -^ statement 
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repetitive-statement 



^ 



repeat-statement 



^ 



while-statement 



"> 



*► for-statement 



1- 



repeat-statement 



» ( repeat \ r» | statemeru[ -^p-» (until^ )--» |expression 



O 



wMie-statement 



•»(^ while) — ► expression 



for-statement 

•►TforVl^ control-variable l-W^^=Vl»' initial-value 

V f^ \ , f \- f^ \ , , 



c 



D 



y-l^to; 7^ 



final-value -»(do)-» statement 



contjvJ-vaiiatHe 



^ variable-Identifier ^ 



initiai-value 



■wi expression 



final-vaiue 



^ expression ^ 



with-statmnent 



— ► (with 



withW » 



record-variable-reference 










K*)"^ 



statement 
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Syntax 



C.7 Procedures and FuncUom (see Chapter 7) 

pwcettjiw-cteclatatlon 



procedure-heading -KT/** procedure-body -H^T) — ► 



procedum-txKfy 



1 



block 



^^ — KT^ — > 

— » (extemar ) — ^ 



proceckjw-t^acting 



-»( procedure ) — 1^ 



identifier 



^ 



formal-parameter-llst 



rr 



function-declaration 

function-heading '^Q)^ function-body ■♦(T) — ^^ 



function-body 



"T 



block 



— K ^ external} — 



fUncUon-neaOinq ^( ^^j^^^^^i^^^^ identifier 



c 



D 



TJ 



formal-paraneter-list 



l7 



^T)-> result-type 



result-type 



^ ordlnal-type-identifler 



^ 



real- type-identi f ier 



pointer-type-identifier 
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Syntax 



fif/maJ-paiwneter-JJst 

— (D 



jr. 



parameter-declaration — j — Y"*®""*' 



^'^^ procedure-heading 



-> 



V*. 



function-heading 



O 



pammemr'ileaJafatJm » [ 7(jenUfler-ilst | -»(r)-» rtype-^tientifier 



CJ& Programs (see Chapter 8) 

pwgram 



program-heading -"»(T) 



Vj laxJ 

^ uses-clause P v;J-^ 



■♦Hbloc*: 



ptt^^^am-neacffng 



— » (prDgram^ identifier 



Vdh 



program-parameters 



. !► 



fmrBm-parmieters , | laenofler-ust 



uses-Clause 



-» (^uses) ► 



identifier-list 
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a9 UhiU (see Chapter 9) 

reqular-unit » | unit-heading | -»(7> 



J 



^ interface-part -» implementation-part •^ C^n^^ '^CO — ^ 



unlt-heactlnq ^ f^j^JD - ^ identifier 



lntm^zmL^(^^y 



T 



''^ uses-clause 



'^ 



^ constant-declaration-part 



b 



b 



^ type-declaration-part 



'^ 



b 



^ variadle-declaration-part 



^ 



D 



^ procedure-and-function-declaration-part 



implementation-part ^ ^ implementaJi^ 



J 



^ constait-declaration-part 



r 



^ type-declaration-part 



b 



r- 



b 



^ variable-declaration-part 



r 



b 



^ procedure-and-function-declaration-part 



^--^ 
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Floating-Point Arithmetic 



D.1 MnxJuction 

Floating-point aritfinetic in Pascal on the Lisa (all arithmetic invralving real 
values) conforms to most of the single-precision aspects of the IEEE's Pn^xjsed 
Standarct for Binary Floating-Point Arithmetic (Draft 10.0 of IEEE Task P754)l 

IEEE Standard arithmetic provides better accuracy than many other floating- 
point implementations. It also reduces the problems of overflow, tnderflow, 
limited precision, and Invalid operations by providing useful ways of dealing 
with them. 

The FPLIB library unit (in the file lOSFPLIB) contains the routines that perform 
floating-point arithmetic (including all the transcendental functions and the 
sqrt fmction). FPLIB must be linked into any program that uses floating-fxjint 
arithmetic; however, it is not necessary to explicitly refer to FPLIB in a us^ 
clause unless U« program calls the specialized sup^rt procedures and 
functions declared in the interface of FPLIB. 

This manual assumes that you do not explicitly use the FPLIB mit, and that 
therefore only the default options of IEEE arithmetic are applicable. 

As a general rule, you can write Lisa Pascal prograrm that use f Icraiting-point 
arithmetic without worrying about the differences between IEEE Standard 
arithmetic and other flcrating-point impler^ntations. 

The following points apply if your program writes out floating-point numbers as 
textual representations (via write or writeln): 

• Anything in the output that looks like a number will be correct (and 
possibly rrwre accurate than inder otf«r inplemoitations). 

• If your output contains a string of two or more pluses or minuses, this 
indicates a value of «, resulting from division by zero or some other 
operation that caused a floating-point overflow. 

• If your output contains the string "NaN" (meaning Not a Number), this 
indicates tt% result of some invalid qperation that would probably have 
caused a program halt or a wnxig output under other irr^lemmtations. 
Note that any lesfl value in text outptk that does not include the string 
"NaN" is guaranteed not to have been affected by any invalid operation. 

D.2 Rounifing of Real Results 

When a real result must be rounded, it is always rounded to the nearest 
representable real value. If the unrounded result is exactly halfway between 
two representable real values, it is rounded to the value that has a zero in the 
least significant digit of its binary fraction (the "even" value). 
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D.3 Accxiracy of Arithmetic Gperations 

The arithmetic operations *, -, * i, rounds tiunc, and sqrt are accurate to 
within half a unit in the last bit. Remainders are computed without rounding 
error. 

D.4 Overflow and Oivisian by Zero: Infinite Values 

The result of floating-point overflow is either « or -«». These are values of 
type real that can be used in further calculations and follow the mathematical 
conventions: for example, a finite number divided by » yields zero. 

Dividing a finite non-zero value by zero also yields « or -<» (in floating-point 
arithmeticJL 

Infinite values have textual representations that can be read by read or readln 
or written out by write or writela 

Tables D-1 and D-2 below show the results of arithmetic operations on 
infinities. Note that any operation involving a NaN as an operand produces a 
NaN as the result 



Table D-1 
Results of Addition and Subtraction on Infinities 



Left 




Right 
cperand 




Cperand 


-00 


finite 


♦00 


-00 

finite 

•t-oo 


+ 


-00 

-co 

NaN 


—00 

finitet 

+00 


NaN 

♦00 
♦00 


-00 

finite 

♦09 


- 


NaN 

+00 

■foa 


-00 

finitet 

♦00 


-00 

—00 

NaN 


f Result Is an Infinity If the operation overflows. 
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Table D-2 
Results of Multiplication and Cttvision on infinities 

Right 
Operand 



Left 
Operand 




±0 


finite 


+« 


±0 
finite 

♦00 


M 


±0 

±0 

NaN 


±0 
finite! 

♦w 


NaN 

♦w 


±0 
finite 

too 


/ 


NaN 

♦eo 


±0 
finite! 

±pa 


±0 
±0 

NaN 


t Result is an infinity if the operation overflows. 


At?te:Sign of result is determined by the usual mathematical rules. 



OS Invalid Operations: NaN Values 

An invalid operation (such as dividing zero by zero) does not cause a halt 
Instead it returns a special diagnostic value^ and execution continues. The 
result of ai invalid operation is called a Nahi which stands for "Not a 
Number." 

A NaN resulting from an invalid operation is a propagating NaN This means 
that if the NaN is used as an operand in another ojaeration, the result of the 
operation will be the same NaN. NaNs can be written out via write or wilteln 
and read via read or readln; the textual representation is "NaN" (optionally 
followed by a quoted strlng)L 

The following operations are invalid arrcJ return a NaN value: 

• OS— ca or co4/-oa^ 

• H +ew 

•0/0 

• ±oo/±<a 

• Tr^ dn^ COS, In, and sqrt functions, when the ar^jments are inappropriate. 

(See the function descriptions in Sections 11.4.4, 11.4.5, 11.4.7, and 11.4.8, 
respectively.) 
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Q6 Integer Com/ersion CVerflow 

integer conversion overflow can occur In tiunc or round (see Chapter 11) if the 
actual-parameter exceeds the bounds of the predeclared type integer. The 
result returned is unspecified. 

D.7 Text-Oriented IA3 Conversions 

The read, readln, write< and writeln procedures require the conversion of 
numbers from decimal to binary on input and from binary to decimal on output. 
The error in these conveniens is less than 1 unit of the result's least 
significant digit (In the past base conversions have rarely been done 
accurately In a way that permits simple error bounds to be put on the results.) 

Real values appear as character strings in two different contexts: as source 
code processed by the compiler (real constants), and in text files written and 
read by Pascal programs. The signed-number syntax of Chapter 1 applies in 
both cases. However^ the compiler does not accept Infinities and NaNs. 

For read and write, +«» is represented by a string of at least two plus signs, 
and -w by a string of at least two minus signs. NaNs are represented by the 
characters "NaN", with an optional leading sign, and an optional trailing quoted 
string of characters; an example is 

-NaN12:34* 

The character string is sometimes used to provide diagnostic data 

D.8 FPL© Interface 

IMPLEMENTATION NOTE 

The IEEE numerics are a proposed standard, and this implementation 
imay be redesigned for future releases. 
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UNIT fplib ; INTRINSIC ; 



{ Use this header for intrinsic 
library. } 



{ FPLIB floating point library version A53^ 29 March 1983 } 
{ Copyright 1983, Apple Computer Inc. } 



{$setc fp_foros 



;= true } 



{$setc fp_testversion := false } 
{$setc fp_conipilersubset := false } 



INTERFACE 



{ True to compile for OS, false for 

Monitor. } 
{ True if special test library. } 
{ True to compile special subset 
library for Pascal compiler, 
false to compile full library. } 



{ 

CONST 



{ CONSTANTS to parameterize floating point types } 



maxfpstring = 80 ; { Declared length of floating point string type. } 
maxfpreg « 1 ; { Floating point registers are numbered Cmaxfpreg } 

{ CONSTANTS for random number generation } 

randmodulus = 2147483647 ; { Prime modulus for random number generator. } 

{ CONSTANTS for NaN Error Codes } 

Invalid Square Root such as sqrt(-l). } 
Invalid Addition such as +INF - +INF. } 
Invalid Conversion to Integer. } 
Invalid division such as 0/0. } 
Trapping NaN encountered. } 
ordered compare of unordered quantities. } 
Invalid use of Infinity in Projective Mode. } 
Invalid Multiply such as * INF. } 
Invalid Remainder or Modulo such as x REM 0. } 
Invalid binary to ascll conversion parameter. } 
Attempt to promote single denorm to double. } 
Attempt to convert nonnormal to single or double. } 
Attempt to convert Invalid ASCII string. } 
Attempt to convert NaN 'invalid string*. } 
AttemJDt to convert unrepresentetole ASCII strlr^. } 
Attempt to convert NaN valued Integer to floating } 



nansqrt 


= 1 ; { 


nanadd 


= 2; { 


nanint 


- 3; { 


nandlv 


= 4; { 


nantrap 


- 5; { 


nanunord 


= 6; { 


neinproj 


- 7 ; { 


nanmul 


= 8; { 


nanrem 


= 9; { 


nanascout 


= 10 ; { 


nanpromote 


- 11 ; { 


nanresult 


= 12 ; { 


nanascbin 


- 17 ; { 


nanascnan 


= 18 ; { 


nanascin 


- 19 ; { 


naninteger 


= 20 ; { 
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nanzero 

nantrlg 

nanlnvtrlg 

nanexp 

nanlog 

nanpower 

nanfinan 

naninlt 



21 ; 
33; 
34; 
35; 
36; 
37; 
38 ; 
255 



Attempt to create a NaN with zero slgnlficand. 
Invalid argument to trig routine. } 
Invalid argument to Inverse trig routine. } 
Invalid argument to b^x for constant b. } 
Invalid argument to log routine. } 
Invalid argument to x"i or x"y routine. } 
Invalid argument to financial function. } 
Uninitialized storage. } 



{— ■ 
TYPE 



•} 



{ TYPES that are subranges } 



fp_regindex = 0..maxfpreg ; { Index In floating point register array. } 

nibble = 0..15 ; {Hex "digit". } 

fp_bcdindex = 0..27 ; { Index in bcdstring type. } 

fp_6blt = 0..63 ; {For six bit fields. } 

byt = 0..255; { Unsigned byte. } 

bite = -128.. +127; { signed byte. } 

{ TYPES that are packed arrays } 

fourblte = packed array [0..3] of bite ; 
eightbite = packed array [0..7] of bite ; 
tenblte = packed array [0..9] of bite ; 

{ TYPES that represent numbers^ infinities^ and NaNs } 



fp_bite = 
f p_int64 = 
fp_double = 
f p_extended = 



bite ; 
eightbite 
eightbite 
tenbite ; 



{ 64 bit Integer with -2 "63 as NaN. } 
{ IEEE double precision floating point. } 
{ IEEE double extended floating point. } 



fp_register - packed record { Floating point register. } 

sign : bite ; { for positive^ -128 for negative } 

tag : bite ; { l=normaL 2=zero^ 4=inf^ 8=NaN^ 16=nonnormal } 

exponent : integer ; 

fraction : eightbite ; { actually slgnlficand } 

end ; 

fp_bcdstring = packed array [fp_bcdindex] of nibble ; { packed bed string } 
fp_string = string[maxfpstring] ; { String parameter. } 
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fp_type = ( tfp_blte, tfp_integer, tfp_longint, tfp_lnt64, 
tfp_real^ tfp double, tfp_extended, tfp_register, 
tfp_bccistring7 tfp_string ) ; { Names for number types } 

{ TYPES that point ) 

pfp_blte = " fp_blte ; 

pfp_integer - * integer ; 

pfp_longint = " longint ; 

pf p_int64 « " f p_int64 ; 

pfp_real = " real ; 

pfp_clouble = * fp_double ; 

pf p_extencled = " f p_extended ; 

pfp_register = ^ fp_register ; 

pfp_bcdstrlng = " fp_bcdstring ; 

pfp_string = ^ fp_string ; 

fpjDOinter = " integer ; { Free pointer to any type. } 

fp_procaddress« fpjx)inter ; { Actually * procedure with no arguments. } 

{ TYPES that provide non-numeric types for floating point use } 

xcpn = ( invop, overfl, underfl, divO, inxact, cvtovfl, fp_xcpn6, fp_xcpn7); 
{ Floating point exceptions: 

invop..inxact are the IEEE exceptions 

ctvovfl is for floating to integer conversion overflow 

fp_xcpn6 and 7 are for future expansion > 

excepset = set of xcpn ; { For handling all exceptions at once. } 

roundtype = (rnear, rzero, rpos, rneg, rout) ; { Rounding modes. } 

fp_cc = (equal, lesser, greater, unord) ; { Results of comparisons. } 

fp_kindtype = ( zero, nonnormal, norml, inf, NaN) ; { Floating operands. } 

fp_format = 

( fp_lisa, fp_free, fp_iround, fp_i, fp_f, fp_el, fp_e2, fp_e3, 

f p_e4, f p e ) ; 

{ Output formats for binary to ascii routines. } 

{ TYPES that provide IEEE arithmetic modes } 

rmode = rnear .. rneg ; { IEEE rounding modes. } 

closure = ( proj, affine ) ; { IEEE infinity modes. } 

denorm = ( warning, normalizing ) ; { IEEE denormalized modes. } 

extprec = ( xprec, spree, dprec ) ; { IEEE rounding precision modes. } 
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{ TYPES that define floating point trapping } 

fp_traprecorcl = record { of information for composite floating point trap } 
neader : Integer ; 

{ <0 for atomic floating point operation from F-line op code 
=0 for composite floating point operation 
>0 for atomic Pascal Real arithmetic operation ) 
es : excepset ; { Exceptions that occurred in this operation. } 
procname : pfp_string ; { procname" contains name of procedure } 
optypel, optype2, resulttype : fp_type ; { Operand and Result types } 
opl, op2, result : fp_pointer ; { Operand and Result pointers } 
end ; 

pf p_traprecord - * fp_traprecord ; 

{ TYPES that define the FLOATING POINT CONTRa BLOCK^ FPCB_ } 

fp_statustype = packed record { Non-numeric floating point status } 
condition : Dite ; { Contains invalid code and fp_cc } 
excep : bite ; { Sticky exception-occurred bits for each xcpn } 
{ Scratch } 

{ Last-operation exception-occurred bits } 
{ Bit for each IEEE mode } 
{ Trap-enabled bits for each xcpn. } 
pfp_traprecord ; { fp_traprecord or last F-line op code } 



array [fp_regindex] of fp_register ; 

fp blocktype = record { Floating point status and numeric registers } 
status : fp_statustype ; 

f : fp_regarray ; { FPCB_.BL0CK.F[1] is "FPi" in comments. } 
end ; 

fpcb_type = packed record { Floating point control block. } 
case boolean of 
false : ( { current definition } 

ptrapvector : array [xcpn] of fp_procaddress ; 

{ Pascal language floating point trap vector. } 
block : f p_blocktype ; 

) ; 
true : ( { obsolete definition for compatibility } 
trapvector : array [0..73 of " longint ; 
condition : bite ; 
excep : bite ; 
tmode : bite ; 
texcep : bite ; 
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tmode : 


bite 


texcep 


: bite 


mode : 


bite 


trap : 


bite 


Instad 


: pfpj 


end ; 




fp_regarray » « 


array [ 
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end 



mode : bite ; 

trap : bite ; 

Instad : longlnt 

f : f p_regarray ; 

unused": array [xcpn] of fpjDrocaddress 

); 



p_f pcb_type = " f pcb_type ; 

{$ifc not fp_testversion } 

{ TYPES for conipatiblllty with previous releases } 
lntl6 = packed array [0..1] of bite ; lnt32 = fourblte ; lnt64 = fp_lnt64 
single - fourblte ; double - fp_double ; extended = fp_extended ; 
fpreglster = fp_register ; fpstrlng = fp_strlng ; condltloncode = fp_cc ; 
fp6blt = fp_6blt ; fpregarray = fp_regarray ; fpklndtype = fp_klndtype ; 
f pcbtype = f pcb_type ; pf pcbtype = p_f pcb_type ; 
{$endQ } 



{- 



•} 



VAR 



{ FLOATING POINT CONTROL BLOCK } 



FPCB_ : f pob_type ; 

{$lfc not fp_compllersubset } 

I 



■} 



{ MICROSEGMENT fpmsub } { Internal assembly language procedures only. } 

^ } 



{ mCROSEGHENT f 32sub } 



function 
function 
function 
function 
function 
function 



f32_minus 
f32_integral 



f32_fraction ( 



f32_ilogb 
f32_scale 
f 32 kind 



real ) 
real ) 
real ) 
real ) 
real ; 
real ) 



boolean ; 
boolean ; 
real ; 
integer ; 
: Integer ) 
fp_kindtype 



{ Sign(x) } 

{ Is X integral? } 

{ Fraction part(x) 

{ Exponent(x) } 

: real ; { x * 2^1 



} 



{ Returns Zero, Norml, Inf or NaN; NonNormal classifies as Norml } 



{$endc } 

function f32_fpcb : p_fpcb_type 

{$ifc not fp_conpilersubset } 



{ Returns aFPCB_ } 
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{- 



{ mCROSEGrCNT UXSOsub } 

{ EXTENDED PRECISION ARITHMETIC } 

{ PROCEDURES for monadic zero address arithmetic } 



procedure f pneg ; { FPO 

procedure f pabs ; { FPO 

procedure fpint ; { FPO 

procedure f psqrt ; { FPO 



= -FPO. } 

= abs(FPO). } 

= integral part of FPO } 

» sqrt(FPO) } 



{ PROCEDURES for dyadic zero address arithmetic } 



procedure f padd ; { FPO 

procedure f psuD ; { FPO 

procedure fpmul ; { FPO 

procedure f pdiv ; { FPO 

procedure f prem ; { FPO 

function fpcom : fp_cc 



FPO * FPl } 
FPO - FPl } 
FPO * FPl } 
FPO / FPl } 
FPO rem FPl 



} 



{ Returns result of fpo compare FPl. } 



{ PROCEDURES for two address arithmetic } 



function 

function 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 



fpints 

fpsqrts 

fpnegd 

fpabsd 

fpintd 

fpsqrtd 

fpnegx 

fpabsx 

fpintx 

fpsqrtx 



X 

x 

var X, 

var X, 

var X, 
var 
var 

var X, 

var X, 

var X, 



real 

real 

z 



) 



X, 
X, 



: real ; 

: real ; 

fp_douDle 

fp_double 

fp_douDle 

fp_douDle 

fp_extended 

fp_extended 

fp_extended 

fp_extended 



integral part of x 
sqrt(x) } 



} 



-X } 
abs(x) } 
integral part of 
sqrt(x) } 
-X } 

al)s(x) } 
integral part of 
sqrt(x) } 



X } 



X } 



{ PROCEDURES for three address arithmetic } 



function fpadds ( x, y : real ) : real ; { 

function fpsubs ( x, y : real ) : real ; { 

function fpmuls ( x, y : real ) : real ; { 

function fpdivs ( x, y : real ) : real ; { 

function fprems ( x, y : real ) : real ; { 

function fpcoms ( x, y : real ) : fp_cc ; 

procedure fpaddd ( var x, y^ z : fp_douDle ) 

procedure f psubd ( var x, y^ z : fp_double ) 

procedure fpmuld ( var x, y^ z : fp_double ) 



-y } 
-y } 
* y > 
/y } 

rem y 



{ z := X + y } 
{ z := X - y } 
{ z := X * y } 
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procedure fpdlvd ( var x, y^ z 

procedure f prerod ( var >c y^ z 

function fpcoind ( var x, y 

procedure fpaddx ( var x, y, z 

procedure f psudx ( var x, y^ z 

procedure fpmulx ( var x, y. z 

procedure fpdlvx ( var x, y^ z 

procedure fpremx ( var x, y^ z 

function fpcofnx ( var x, y 



fp_douCile ] 
fp_doudle ) 
fp^double ) 

fp_extended 
fp_extended 
fp_extended 
fp_extended 
fp_extended 
fp_extended 



{ PROCEDURES for type conversion } 
{ PROCEDURES for FPO :- X } 



procedure wmovef p 
procedure imovefp 
procedure smovefp 
procedure dmovef p 
procedure xmovef p 



( 
( 
( 
( 
( var x 



X 
X 

var X 



integer 

longint 

real 

fp_dout)le 

fp_extended 



{ PROCEDURES for FPl := X } 



procedure wmovefpl ( x 
procedure Imovefpl ( x 
procedure smovefpl ( x 
procedure dmovefpi ( var x 
procedure xmovefpl ( var x 

{ PROCEDURES for Z : 

function fpmovew 
function fpmovel 
function fpmoves 
procedure fpmoved ( var z 
procedure f pmovex ( var z 



integer 

longint 

real 

fp_dout)le 

fp_extended 

' FPO } 



integer ; 
longint ; 
real ; 

fp_doulDle ) ; 
f p_extended ) ; 



{ PROCEDURES f or Z :- X } 



{ z := x/y } 
{ z := X rem y } 
f P_cc ; 



function 

function 

function 

function 

function 

function 

procedure 

procedure 



xmovew 
dmovew 
xniovel 
dmovel 
xmoves 
dfnoves 
wnoved 
Imoved 



( var 


X : 


( var 


X : 


( var 


X : 


( var 


X : 


( var 


X : 


( var 


X : 


( 


X : 


( 


X : 



fp_extended 
fp^douDle 
fp_extended 
fp_douDle 
fp_extended 
fp_doul)le 
integer ; 
longint ; 



{ 
{ 
{ 
{ 
{ 
f p_CC ; 



-y } 
-y } 
*y } 
/y } 

rem y 



: integer ; 
: integer ; 
: longint ; 
: longint ; 
: real ; 
: real 

var z : fp_double 
var z : fpjdoudle 



D-ll 



"SSGsJ r^ST&T&nGu rudKHJdJ 



Floating-Point Arithmetic 



procedure smoved ( 


: X 


real 


v 


procedure xmoved < 


\ var X 


f p extended 


; V 


procedure wnovex ( 


\ X 


integer ; 


var 


procedure imovex ( 


[ X 


longlnt ; 


var 


procedure smovex i 


\ X 


real ; 


var 


procedure dmovex ( 


\ var X 


fp double ; 


var 



: fp_double ) 
: fp_double ) 
f p_extended ) 
f p_extended ) 
f p_extended ) 
f p_extended ) 



procedure cmovefp ( var b : fp_bcdstrlng ) ; 
procedure 164neg ( var x, z : fp_int64 ) ; { z := -x } 
function x80_integral( var x : fp_extended ) : boolean ; 
procedure x80_break ( var x, intx, f racx : fp_extended ; 

var izero^ fzero : boolean ) ; 
{$endc } 
function x80_fpcb : p_fpcb_type ; { Returns aFPCB_ } 



{■ 



{ mCROSEGMENT ufpm } 

{ PROCEDURES for binary to ascii conversion } 



procedure fp_zero_ascii 
( sign : boolean ; 
var s : fp_string 

procedure fp_lnf_ascii ( 
var s : f p_string 



before, after : integer ; format : f p_f ormat 
; var error : boolean ) ; 
sign : boolean ; width : Integer ; 
; var error : boolean ) ; 



{ PROCEDURES for exceptions } 

function getxcpn ( e : xcpn ) : boolean ; 
procedure setxcpn ( e : xcpn ; b : boolean ) ; 
procedure getexcepset ( var es : excepset ) ; 
procedure setexcepset ( es : excepset ) ; 
procedure gettexcepset ( var es : excepset ) ; 
procedure settexcepset ( es : excepset ) ; 
procedure clrexcepset ; 

{ PROCEDURES for trap-enabled bits in FPCB_.BLOCK.STATUS.TRAP } 

procedure gettrapset ( var es : excepset ) ; 
procedure clrtrapset ; { Disables all traps. } 

{ PROCEDURES for floating point trapping } 

procedure fpjx>stoperation ( r : f p_traprecord ) ; 

( Imitates effect of atomic floating point operation by using r.es 
as the set of exceptions generated by a composite operation } 
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procedure cnecktrap ( r : f p_traprecord ) ; 
{$ifc not fpjcompilersubset } 



( _ J 

{ mCROSEGf€NT ux80 } 

{ PROCEDURES that tell about FPO } 

function fpminus : boolean ; { FPO has sign bit on? } 

function fpkind : fp_klndtype ; { Returns type of argument in FPO. > 

{ PROCEDURES that tell about extended X > 

function fpmlnusx ( var x : fp_extended ) : boolean ; { sign bit? } 
function fpklndx ( var x : f p_extended ) : fp_kindtype ; { kind? } 

procedure copysign ( var x, y^ z : fp_extended ) ; 

{ z gets y with sign of x. } 
procedure infinity ( var z : fp_extended ) ; { z :» +INF. > 
procedure errornan ( error : byt ; var z : f p_extended ) ; 

{ Creates a NaN in z with error code set^ other fields 

zero^ and signals Invop xcpn. } 
procedure createnan ( trap : boolean ; extension : fp_&bit ; 

error^ index : byt ; var z : f p_extended ) ; 

{ Creates a NaN in z with 23 significant bits defined. } 
procedure checknan ( var x, z : f p_extended ) ; 

{ z := x but if x is a trapping NaN^ the trapping bit of z is 

turned off and the Invalid flag is set. } 
procedure NaN_parts ( var x : fp_extended ; 

var trap : boolean ; var extension : fp_6blt ; 

var error, index, index2 : byt ; var lowpart : fpjprocaddress ) ; 

{ Splits up X into its conponent parts, lowpart gets the four 

least significant bytes. } 
procedure choosenan ( var x, y, z : f p_extended ) ; 

{ X or y must be a NaN. z is set to whichever has the greater 

Error field, z is non trapping. If either x or y is trapping, 

the Invalid flag is set. } 

{ PROCEDURES that act on numbers but do not use arithmetic } 

procedure fpswap ; { Exchange FPO and FPl } 

procedure blockprelude ( var fpb : fp_blocktype ) ; 

procedure blockpostlude ( var fpb : fp_blocktype ; var trapcoming : boolean); 

^ J 
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{ MICR0SE6MENT uxSOelem } 

{ PROCEDURES that tell about extended X } 
function llogb ( var x : fp_extended ) : integer ; { exponent of x } 

{ PROCEDURES that produce extended Z } 

procedure fpscalex { z :« x * 2"! } 

( var x : fp_extended ; i : integer ; var z : fp_extended ) ; 

procedure scalb { z := x * 2*y for integral y } 

( var X, y, z : fp_extended ) ; 

{ elefnentary function PROCEDURES that require initelem } 

procedure exp2 ( var x, z : fp_extended ) ; { z := 2''x } 
procedure expe ( var x< z : fp_extended ) ; { z := e*x } 
procedure exp2i ( var x, z : fp_extended ) ; { z :* 2"x -i } 

procedure log2 ( var x, z : fp_extended ) ; { z := log(x )/log(2) } 

procedure loge ( var >;, z : fp_extended ) ; { z := log(x )/log(e) } 

procedure logio ( var x, z : fp_extended ) ; { z := log( x )/log(lO) } 

procedure 10yl2 ( var x, z : fp_extended ) ; { z :» log2(l*x ) } 

procedure xtoy ( var x, y^ z : fp^extended ) ; { z := x*y } 

procedure conipound ( var r^ p^ z : fp_extended ) ; { z :- (l+r)*p } 
procedure annuity ( var r. p, z : fp_extended ) ; { z := (l - (l+rr-p)/r } 

procedure postdyadic( name : fp_string ; var x,y.z : fp_extended ) ; 
procedure xpwry ( var x : fp_extended ; y : integer ; var z : fp_extended); 
procedure xexpy ( var x, y , z : fp_extended ) ; 

{ MICROSEGTCNT ux80trig } 



procedure pivalue ( var z 


fp_extended ) ; { z := pi } 


procedure sinx ( var x, z 


fp_extended ) ; { z :« sin(x) } 


procedure cosx ( var x, z 


fp_extended ) ; 


procedure tanx ( var x. z 


f p extended ) ; 


procedure asin ( var x, z 


fp_extended ) ; { z := arcsin(x) } 


procedure acos ( var x. z 


f p extended ) ; 


procedure atan ( var x, z 


f p_extended ) ; 


{$endc} 

/ 
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{ MICROSEGMENT Uf 32 } 



function f32_pwrten(n .-integer): real ; 



{ Does pwrten(n). } 



function f52_exp ( x : real ) : real 
function f 32_ln ( x : real ) : real 
function f 32_sin ( x : real ) : real 
function f 32_cos ( x : real ) : real 
function f 32_atan ( x : real ) : real 
procedure f32_trap ; { Floating Point Trapping for Pascal Real Arithmetic } 

{ J 

{ MICROSEGMENT f 32in } 

{ simple PROCEDURES to convert ascii to binary } 

function p_f32 ( var s : fp_string ) : real ; 

function f32_r_r ( var f : text ) : real ; { Does read(f^real) } 

{ general PROCEDURES to convert ascii to binary } 

procedure read_f32 ( var Inf ile : text ; var Readchars : fp_string ; 

var Z : real ; var Error : txwlean ) ; {1, Readchars get input } 
procedure asciireal 

( Fileio : boolean ; var Infile : text ; 

var S :fp_string ; Firsts Last : integer ; var Next : Integer ; 

var Z : real ; var Error : boolean ) ; 

( } 

{ MICROSEGMENT f 320Ut } 

{ sinple PROCEDURES to convert binary to ascii } 

procedure f 32_w_e ( var f : text ; x : real ; width : integer ) ; 

{ Does write(f,x: width) } 
procedure f32_w_f ( var f : text ; x : real ; widths after : integer ) ; 

{ Does write(f.x:width:after) } 
{$ifc not fp_compilersubset } 

{ general PROCEDURES to convert binary to ascii } 

procedure f32_nan_ascii ( x : real ; width : integer ; 

var s : fp_string ; var error : boolean ) ; 
procedure f32_f_ascii ( x : real ; beforepoint : boolean ; after : integer; 

var s : fp_string ; var error : boolean ) ; 
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procedure f32_e_ascll ( x : real ; before, after, ew : Integer ; 
var s : fp_strlng ; var error : boolean ) ; 



{■ 



{ HICROSEGMENT X80in } 

{ general PROCEDURES to convert ascli to binary } 

procedure pnovefp ( var S : fp string ; First, Last : Integer ; 
var Next : Integer ; var Error : boolean ) ; { FPO := S } 

procedure ascllmovex ( Fllelo : boolean ; var Inf lie : text ; 

var S : fp^string ; First, Last : integer ; var Next : integer ; 
var X : fp_extended ; var Error : boolean ) ; 



{ 

{ MICROSEGMENT x800Ut } 

{ general PROCEDURES to convert binary to ascil ) 



■} 



procedure x80. 

var s* 
procedure x80. 

var s 
procedure xBO. 

var s 
procedure x80. 

after 

var s 
procedure x80 

var s" 
procedure x80 

width, 

var s 
procedure x80 

Width, 

var S 



.nan_ascil ( 
": fp_string j 
l_ascll ( 
: "fp_string j 
ir_ascli ( 
: fp_string , 
f_ascll ( 
: integer ; 
: fp_string , 



var X : fp_extended 
var error : boolean 
var X : fp_extended . 
var error : boolean 
var X : fp^extended , 
var error : boolean 
var X : fp_extended . 



width : inteoer 



beforepoint : boolean 



var error : boolean 
e_ascii ( var x : fp_extended ; before, after, ew : integer 
: fp^strinig ; var error : boolean ) ; 
freelascii ( var x : fp_extended ; 
maxsig : integer ; format : fp_format ; 
: fp string ; var error : boolean ) ; 
ascil ( var X : fp_extended ; 
Before, After : integer"; Format : fp_Format ; 
: fp_string ; var Error : boolean ) ; 



procedure x_eform ( var x : 
var'sigma : integer 

procedure x_if orm ( var x : 
var Sigma : integer 



{■ 



fp_extended ; n : integer ; 

; var s : fp_string ; var e : integer ) 

fp_extended ; 

; var s : fp_string ; var e : integer ) 
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{ mCROSEGMENT fpllbZ } 

{ PROCEDURES that act on numbers but do not use arithmetic } 



procedure movef p ( var x 
procedure movef pi ( var x 
procedure f pmove ( var z 
procedure fplmove( var z 



fp_reglster ) 



{ FPO := X 

fp_register ) ; { FPl :» x 

; f z := FPO 

; { Z := FPl 



fp_reglster 
fp_reglster 



{ PROCEDURES for 64 Dlt Integers } 



procedure i64abs ( var x, z : fp_lnt64 
procedure i64mfp ( var x : fp_int64 ) 
procedure i64mfpl ( var x : fp_lnt64 ) 
procedure fpmovel64 ( var z : fp_lnt64 ) 



) ; { z := abs(x) } 



{ PROCEDURES that produce extended z } 

procedure logb ( var x, z : fpjextended ) ; { z := exponent (x). } 
procedure nextaf ter ( var x, y^ z : f p_extended ) ; 

{ z gets the next number from x in the direction y, 
observing current rounding precision mode. } 



{ 

procechjre 
procedure 

( 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 



elementary function PROCEDURES that require initelem } 
z : fp_extended ) ; { z :- e } 



evalue( var 
xtoi 



( var X, 
( var X, 



var X 
expel 
logle 

slnhx ( var x, 
coshx ( var x, 
tanhx ( var x, 
abs2x ( var x, 
atan2x( var x. 



fp_extended ; i : integer 



z :- e 

{ z : 
var 



fp_extended 
fp_extended 
fp_extended 
fp_extended 
fp_extended 



fp_extended 
fpjextended 



x'^i } 
z : fp_extended 
{ z := expe(x)-l } 
{ z :» loge(l+x ) } 
{ z := slnh(x) } 
{ z := cosh(x) } 
{ z := tanh(x) } 
) ; { z := abs(x+iy) } 
) ; { z := atan(x/y) } 



{ simple PROCEDURES to convert ascil to binary } 



procedure pmoved ( var s 
procedure pmovex ( var s 



fp_string ; var x : fp_double ) ; 
f p_string ; var x : f p_extended ) ; 



{ simple PROCEDURES to convert binary X to ascil S in fp_llsa format } 
{ Comments indicate logical length of s. } 



procedure dmovep ( var x : fp_double ; var s 
procedure xmovep ( var x : f p_extended ; var s 



fp_strlng ) ; { 24 } 
fp_string ) ; { 27 } 
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{ PROCEDURES for use Dy Basic and other language processors } 

function nextrandom ( lastrandom : longlnt ) : longint ; 

(** Returns random longint with 1 <- nextrandom <- randmodulus *) 
procedure x80_maxform ( var x : fp_extended ; 

var Sigma : Integer ; var s : fp_strlng ; var e : Integer ) ; 
procedure x80_eform ( var x : fp_extended ; 

var Sigma : Integer ; var s : fp_string ; var e : Integer ) ; 

{ PROCEDURES for exceptions ) 

procedure excepname ( e : xcpn ; var name : fp_strlng ) ; 

{ Returns exception name: after excepname( Invop, name ), 
name = 'Invop' } 
{$endc } 

{ PROCEDURES to get and set IEEE arithmetic modes } 

function getround : rmode ; 
procedure setround ( x : rmode ) ; 
{$ifc not fp_compller subset } 
function getclos : closure ; 
procedure setnios ( x % olosure ) ; 
function getdnorm : denorm ; 
procedure setdnorm ( x : denorm ) ; 
function getprec : extprec ; 
procedure setprec ( x : extprec ) ; 

{ PROCEDURES for trap-enaDied bits in fpcb_. block. status. trap } 

function gethalt ( e : xcpn ) : boolean ; 
procedure sethalt ( e : xcpn ; b : boolean ) ; 
procedure settrapset ( es : excepset ) ; 

{ PROCEDURES for Pascal trap handlers in FPCB_.PTRAPVECTOR } 

function gettrap ( e : xcpn ) : fpjprocaddress ; { FPCB_.ptrapvector[e] } 
procedure settrap ( e : xcpn ; f : fpjjrocaddress ) ; 
{ FPCB_.ptrapvector[ei := f } 

{$endc ) 

( } 
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{ mCROSEGHENT ulnitfp } 

{ FLOATING POINT INITIALIZATION } 

procedure initfp ; { Initialize the floating point control Block FPCB_. } 
{$lfc not fp_compilersubset } 

procedure initfptrap ; { initialize maximal floating point trapping. } 
procedure initelem ; { Initialize FPCB_ and elementary functions. } 

^ } 

{ PROCEDURES that are noops^ used to load segments } 

procedure Idfpmodes ; { in segment fpmodes } 

procedure idf 32 ; { in segment ldf32 } 

procedure ldx80 ; { in segment x80 > 

procedure Idxsoelem ; { in segment x80elem } 

( J 

{$endc } 
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E.1 /Sbout TMs /^ppenciix 

This appendix describes QuickDraw, a set of graphics procecftjres, functions, 
and data types that allows a Pascal or assembly-language programmer of Lisa 
to perform highly conplex graphic operations very easily and very quickly. It 
covers the graphic concepts behind QuickDraw, as well as the technical 
details of the data types, procedures, and functions you will use in your 
programs. 

We assume that you are familiar with the Lisa Workshop Manager, Lisa Pascal, 
and the Lisa Operating System's memory management This graphics package 
is for programmers, not end users. Although QuickDraw may be used from 
either Pascal or assembly language, all examples are given in their Pascal 
form, to be clear, concise, and more intuitive; Section E.ll describes the 
details Of the assembly-language Interface to QuickDraw. 

The appendix begins with an introduction to QuickDraw and what you can do 
with it (Section E.2). It then steps back a little and looks at the mathemat- 
ical concepts that form the foundation for QuickDraw: coordinate planes, 
points, and rectangles (Section E.5). Once you understand these concepts, read 
on to section E.4, which describes the graphic entities based on them— how 
the mathematical world of planes and rectangles Is translated into the 
physical phenomena of light and shadow. 

Then comes some discussion of how to use several graphics ports (Section E.6), 
a sunrvmary of the basic drawing process (Section E.7), and a discussion of two 
more parts of QuickDraw, pictures and polygons (Section E.8). 

Next, in Section E.9, there's a detailed description of all QuickDraw proce- 
dures and functions, their parameters, calling protocol, effects, side effects, 
and so on— all the technical information you'll need each time you write a 
program for the Lisa. 

Following these descriptions are sections that will not be of interest to all 
readers. Special Information Is given in section E.io for programmers who 
want to customize QuickDraw operations by overriding the standard drawing 
procedures, in section E.il for those who will be using QuickDraw from 
assembly language, and in Section E.12 for those interested in creating 
three-dimensional graphics using the Graf3D unit 

Finally, there are listings of the QuickDraw interface (Section E.13), two 
sample programs (Section E.14), and the QDSupport unit (E.15); and a glossary 
that explains terms that may be unfamiliar to you (Section E.16). 
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E2 Atxxil QuickDraw 

QuickDraw allows you to organize the Lisa screen into a number of individual 
areas. Within each area you can draw many things^ as illustrated In Figure 
E-l. 
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Figure E-l 
Samples of QidckDraw's Abilities 

You can draw: 

• Text characters in a number of proportionally-spaced fonts^ with variations 
that include boldfacing, italicizing, underlining, and outlining. 

• straight lines of any length and width. 

• A variety of shapes, either solid or hollow, including; rectangles, with or 
without rounded corners; full circles and ovals or wedge-shaped sections; 
and polygons. 

• Any other arbitrary shape or collection of shapes, again either solid or 
hollow. 

• A picture consisting of any combination of the above items, with Just a 
single procedure call. 

In addition, QuickDraw has some other abilities that you won't find in many 
other graphics packages. These abilities take care of most of the "house- 
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keeping"— the trivial but time-consuming and bothersome ovemead that's 
necessary to keep things in order. 

• The ability to define many distinct ports on the screen, each with its own 
complete drawing environment—its own coordinate system, drawing 
location, character set, location on the screen, and so on. You can easily 
switch from one such port to another. 

• Full and complete clipping to arbitrary areas, so that drawing will occur 
only where you want It's like a super-duper coloring book that won't let 
you color outside the lines. You don't have to worry about accidentally 
drawing over something else on the screen, or drawing off the screen and 
destroying memory. 

• Off-screen drawing. Anything you Ccn draw on the screen, you can draw 
Into an off-screen buffer, so you can prepare an image for an output 
device without disturbing the screen, or you can prepare a picture and 
move It onto the screen very quickly. 

And QuickDraw lives up to its name! It's very fast. The speed and 
responsiveness of the Lisa user interface are due primarily to the speed of the 
GjulckDraw package. You can do good-quality animation, fast interactive 
graphics, and complex yet speedy text displays using the full features of 
QuickDraw. This means you don't have to bypass the general-purpose 
QuickDraw routines by writing a lot of special routines to Improve speed. 

E.2.1 How To Use QuickDraw 

QuickDraw can be used from either Pascal or MC68000 machine language. It 
has no user Interface of Its owa 

If you're using Pascal; you must write a Pascal program that Includes the 
proper QuickDraw calls, compile It against the files QD/QulckDraw.(BJ and 
QD/QDSupportOBJ, link It with the files listed In QDA3DStuff.TEXT, and 
execute the linked object file. 

If you're using: machine lahguagCiyour program should Include the proper 
QuickDraw calisrand .INdLODE the file QO/GRAFrYPES.TEXT. Assef7«)le the 
program, link It with the files listed In QD/QDStuff.TEXT, and execute the 
linked object file. 

A programming model, QDSampie, is included with the workshop software in 
the file QD/QOSamplaTEXT (listed in section E.14.1); it shows the structure of 
a properly organized QuickDraw program. What's best for beginners Is to read 
through the text, and, using the superstructure of the program as a "shell", 
modify it to suit your own purposes. Once you get the hang of writing 
programs inside the presupplied shell, you can work on changing the shell 
itself. 

Note that all files related to QuickDraw are prefixed by "QD/". 

QuickDraw Includes only the graphics and utility procedures and functions 
you'll need to create graphics on the screen. Procedures for dealing with the 
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"/mouse, curson, keyboard, and screen settings, as well as those allowing you to 
generate sounds and read and set clocks and dates, are described in Appendix 
F, Hardware interface. 



E^^ QuickDraw DatSTypes 

QuickDraw defines three general data types, CJDByte, QDPUr^and QDHandle: 

type QOByte = -128.. 127 " — 

QOPtr = ''QOByte 
QDHandle = "QOPtr 

other data types are described throughout this appendix in the sections in 
which they're relevant. For a summary of all QuickDraw data types, see 
Section E.13.2. 

E.3 The Mathematical Foundation of QuickDraw 

To create graphics that are both precise and pretty requires not super-charged 
features but a firm mathematical foundation for the features you have. If the 
mathematics that underlie a graphics package are Imprecise or fuzzy, the 
graphics will be, too. QuickDraw defines some clear mathematical constructs 
that are widely used In its procedures, functions, and data types: the coorai- 
nate plane, the point, the rectangle, and the region 

E.3.1 The Coordinate Plane 

All information about location, placement, or movement that you give to 
QuickDraw is in terms of coordinates on a plane. The coordinate plane is a 
two-dimensional grid, as illustrated in Figure E-2. 
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Figure E-2 
The Coonflnate Plane 
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There are two distinctive features of the QuickDraw coordinate plane: 

• All grid coordinates are Integers. 

• All grid lines are Infinitely thin. 

These concepts are Important! Firsts they mean that the QuickDraw plane is 
finite^ not Infinite (although it's very large). Horizontal coordinates range 
from -32768 to +32767^ and vertical coordinates have the same range. 

second, they mean that all elements represented on the coordinate plane are 
mathematically pure. Mathematical calculations using integer arithmetic will 
produce intuitively correct results. If you keep in mind that grid lines are 
infinitely thin, you'll never have "endpoint paranoia"— the confusion that 
results from not knowing whether that last dot is included in the line. 

E.3^ Points 

On the coordinate plane are 4,294,967,2% unique points. Each point is at the 
intersection of a horizontal grid line and a vertical grid line. As the grid lines 
are Infinitely thin, a point Is infinitely small. Of course there are more points 
on this grid than there are dots on the Lisa screen: when using QuickDraw you 
associate small parts of the grid with areas on the screen, so that you aren't 
bound Into an arbitrary, limited coordinate system. 

The coordinate origin (0/J) Is In the middle of the grid. Horizontal coordinates 
Increase as you move from left to right, and vertical coordinates Increase as 
you move from top to bottom. This Is the way both a TV screen and a page 
of English text are scanned: from the top left to the bottom right. 

You can store the coordinates of a point In a Pascal variable whose type Is 
defined by QuickDraw. The type Point Is a record of two Integers, and has 
the following structure: . ^^ 

type VHSeleot = (V,H); 

Point = record case integer of 

0: (v: Integer; 
h: integer); 

1: (vh: array [VHSelect] of Integer) 

end; 

The variant part allows you to access the vertical and horizontal components 
of a point either Individually or as an array. For example. If the variable 
goodPt were declared to be of type Point, the following would all refer to the 
coordinate parts of the point: 

goodPt.v goodPt.h 

goodPt.vh[V] goodPt.vh[H] 
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E.3.3 Rectangles 

PTfj two points can define the top left and bottom right comers of a 
rectangle. As these points are Infinitely small the borders of the rectangle 
are Infinitely thin (see Figure E-3). 
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Figure E-3 

A R^taTiyie 



Rectangles are used to define active areas on the screen, to assign coordinate 
systems to graphic entities, and to specify the locations and sizes for various 
drawing commands. QuickDraw also allows you to perform many 
mathematical calculations on rectangles— changing their sizes, shifting them 
around, and so on. 

NOTE 

Remember that rectangles, like points, are mathematical concepts that 
have no direct representation on the screen. The association between 
these conceptual elements and their physical representations is made by 
a bitmap, described below. 
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The data type for rectangles Is Rect, and consists of four Integers or two 
points: 

type Rect = record case Integer of 

0: (top: integers- 
left: integer; 
. / bottom: integer; 
( ( right: integer); 

1: (topLeft: Point; 
DotRight: Point) 

end; 

Agaia the record variant allows you to access a variable of type Rect elUier 
as four boundary coordinates or as two diagonally opposing comer points, 
combined with the record variant for points^ all of the following references to 
the rectangle named bRect are legal: 

bRect {type Rect} 

bRect. topLeft bRect .botRight {type Point} 

bRect. top bRect. left {type integer! 
bRect. topLeft.v bRect. topLeft.h {type integer} 
bRect. topLeft.vh[v] bRect. topLeft.vn[H] {type integer} 

bRect. bottom bRect. right {type integer} 
bRect.botRic^t.v bRect. botRight. h {type integer} 
bRect. botRight. vh[V] bRect. botRight. vh[H] {type integer} 

WARNING . 

If the bottom coordinate of a rectangle is equal to or less than the top, 
or the right coordinate is equal to or less than the left, the rectangle 
is an empty rectangle (i.e., one that contains no bits)L 

E.3.4 Regions 

Unlike most graphics packages that can manipulate only simple geometric 
structures (usually rectilinear, at that), QuickDraw can gather an arbitrary set 
of spatially coherent points into a structure called a region, and perform 
complex yet rapid manipulations and calculations on such structures. This 
remarkable feature not only will make your standard programs simpler and 
faster, but will let you perform operations that would otherwise be nearly 
Impossible; it is fundamental to the Lisa user interface. 
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You define a region by drawing lines, shapes such as rectangles and ovals, or 
even other regions. The outline of a region should be one or more closed 
loops. A region can be concave or convex, can consist of one area or many 
disjoint areas, and can even have "holes" In the middle. In Figure E-4, the 
region on the left has a hole In the middle, and the region on the right 
consists of two disjoint areas. 






Figure E-4 
Regions 

Because a region can be any arbitrary area or set of areas on the coordinate 
plane. It takes a variable arnount of information to store the outline of a 
region. The data structure for a region, therefore. Is a variable-length entity 
with two fixed fields at the beginning, followed by a variable-length data 
field: 

type Region = record 

rgnSize: Integer; 
rgnBBox: Rect; 

{optional region definition data} 
end; 

The rgnslze field contains the size, in bytes, of the region variable. The 
rgnl^ox field is a rectangle which completely encloses the region. 

The simplest region is a rectangle. In this case, the ignBBox field defines the 
entire region, and there is no optional region data For rectangular regions (or 
empty regions), the ignSize field contains 10 (two bytes for rgnSize, plus 
eight for rgnBBox). 

The region definition data for rKxirectangular regions is stored in a compact 
way which allows for highly efficient access by QuickDraw procedures. 
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As regions are of variable size^ they are stored dynamically on the heap, and 
the Operating System's memory management moves them around as their sizes 
Change. Being dynamic, a region can be accessed,only thtcx^gha^pQiateri but 
when a region Is moved, all pointers iref erring to it must be updated. For tRis 
reason, all regions are accessed through hancaes;, which point to one master 
pointer which in turn points to the region. 

type RgnPtr = ^Region; 
RgnHandle = *RgnPtr; 

When the memory management relocates a region's data In memory. It updates 
only the RgnPtr master pointer to that region. The references through the 
master pointer can find the region's new home, but any references pointing 
directly to the region's previous position In memory would now point at dead 
bits. To access individual fields of a region, use the region handle and double 
Indirection: 

iiiyRgn^''.rgnslze {size of region whose handle is myRgn} 

RQfRgn^^.rgnBBox (rectangle enclosing the same region} 

ii^rt^^^.rgnBBox.top {minimum vertical coordinate of all points 

in the region} 
RiyRgn^.rgnBBox {semantically incorrect; will not compile if 

myRgn is a rgnHandle} 

Regions are created by a QuickDraw function which allocates space for the 
region, creates a master pointer, and returns a region handle. When you're 
done with a region, you dispose of it with another QuickDraw routine which 
frees up the space used by the region. Only these calls allocate or deallocate 
regions; do not use the Pascal procedure new to create a new region! 

You specify the outline of a region with procedures that draw lines and 
shapes, as described In Section E.9, QuickDraw Routines. An example Is given 
In the discussion of closeRgn in section E.9.11, calculations with Regions. 

Many calculations can be performed on regions. A region can be "expanded" 
or "shrunk" and, given any two regions, QuickDraw can find their union. 
Intersection, difference, and exclusIve-OR; it can also determine whether a 
given point or rectangle Intersects a given region, and so on. There Is of 
course a set of graphic operations on regions to draw them on the screen. 

E.4 GrapTiic Entities 

Coordinate planes, points, rectangles, and regions are all good mathematical 
models, but they aren't really graphic elements—they don't have a direct 
physical appearance, some graphic entitles that do have a direct graphic 
Interpretation are the bit image, bitmap, pattern and cursor. This section 
describes the data structure of these graphic entitles and how they relate to 
the mathematical constructs described above. 

E.4.1 The Bit image 

A bit Image Is a collection of bits In memory which have a rectilinear 
representation. Take a collection of words in memory and lay them end to 
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end so that bit 15 of the lowest-numhered word Is on the left and bit of 
the highest-numbered word is on the far right Then take this array of bits 
and divide it, on word boundaries, into a number of equal-size rows, stack 
these rows vertically so that the first row is on the top and the last row is on 
the bottom. The result Is a matrix like the one shown In Figure E-5— rows 
and columns of bits, with each row containing the same number of bytes. The 
number of bytes in each row of the bit Image Is called the row wiam of that 
image. 



First 
Byte 




Row width 
is 8 bytes 



Last 
Byte 



Figure E-5 
A Bit Image 

A bit image can be stored in any static or dynamic variable^ and can be of 
any length that Is a multiple of the row width. 

The Lisa screen Itself Is one large visible bit image. There are 32,760 bytes of 
menfKjry that are displayed as a matrix of 262,080 pixels on the screen, each 
bit corresponding to one pixel. If a bit's value is 0, Its pixel is white; if the 
bit's value is i, the pixel is black. 

The screen is 364 pixels tall and 720 pixels wide, and the row width of Its bit 
image is 90 bytes. Each pixel on the screen is one and a half times taller 
^than it is wide, meaning a rectangle 30 pixels wide by 20 tall looks square, 
and a 30 by 20 oval looks circular. There are 90 pixels per Inch horizontally, 
and 60 _per inch vertically. '^ 
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NOTE 



Since each pixel on the screen represents one bit in a bit Image, 
wherever this appendix says "bit", you can substitute "pixel" if the bit 
Image is the Lisa screen. Likewise, this appendix often refers to pixels 
on the screen where the discussion applies equally to bits in an 
off-screen bit image. 



E.4.2 The Bitmap 

When you combine the physical entity of a bit image with the conceptual 
entitles of the coordinate plane and rectangle, you get a bitmap. A bitmap 
has three parts: a pointer to a bit image, the row width (in bytes) of that 
image, and a boundary rectangle which gives the bitmap both Its dimensions 
and a coordinate system. Notice that a bitmap does not actually Include the 
bits themselves: It points to them. 

There can be several bitmaps pointing to the same bit Image, each imposing a 
different coordinate system on it This important feature is explained more 
fully in Section E.6. Coordinates in GrafPorts. 

As shown in Figure E-6. the data structure of a bitmap is as follows: 

type Blttlap - record 

baseAddr: QDPtr; 
roieytes: integer; 
bounds: Rect 
end; 



Address 



baseAddr 



rowByte s 
bounds 




Figure E-6 
A Bitmap 
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The base/Nddr field Is a pointer to the beglnnlnci of the bit Image In memory, 
and the lowBytes field is the number of bytes in each row of the image. Both 
of these should always be even: a bitmap should always begin on a word 
boundary and contain an integral number of words in each row. 

The bounds field is a boundary rectangle that both encloses the active area of 
the bit image and imposes a coordinate system on It The relationship 
between the boundary rectangle and the bit image in a bitmap is simple yet 
very important. First, a few general rules: 

• Bits in a bit image fall between points on the coordinate plane. 

• A rectangle divides a bit image into two sets of bits: those bits inside the 
reotaigle and those outside the rectsngle. 

• A rectangle that is H points wide and V points tall encloses exactly 
(H-l) * (V-1) bits. 

The top left comer of the boundary rectangle is aligned around the first bit in 
the bit image. The width of the rectangle determines how many bits of one 
row are logically owned \y^ the bitmap; the relationship 

8 * map.rovBytes >» nep. bounds. right-map. bounds. left 

must always be true. The height of the rectangle determines how many rows 
of the image are logically owned by the bitmap. To ensure that the number 
of bits in the logical bitmap is not larger than the number of bits in the bit 
Image, the bit image must be at least as big as 

(map. bounds .bottom-map .bounds .top)«map .rowBytes 

Normally, the boundary rectangle conrpletely encloses the bit image: the width 
of the boundary rectangle is equal to the number of bits in one row of the 
image, and the height of the rectangle is equal to the number of rows in the 
image. If the rectangle is smaller than the dimensions of the image, the least 
significant bits in each row, as well as the last rows in the image, are not 
affected by any operations on the bitmap. 

The bitmap also imposes a coordinate system on the image. Because bits fall 
between coordinate points, the coordinate system assigns integer values to the 
lines that border and separate bits, not to the bit positions themselves. For 
example, if a bitmap is assigned the boundary rectangle with corners (10,-8) 
and (54,8), the bottom right bit in the image will be between horizontal 
coordinates 33 and 34, and between vertical coordinates 7 and 8 (see Figure 

E-7). 
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(10,-8) 



(34,-8) 



I I I III I I I I I I I I I I I I I I I [ I ' 



(10,8) 



(34,8) 



Figure E-7 
coordinates and Bitmaps 



E.43 Patterns 

A pattern is a 64-bit image^ organized as an 8-by-8-bit rectangle^ which is 
used to define a repeating design (such as stripes) or tone (such as gray). 
Patterns can be used to draw lines and shapes or to fill areas on the screen. 

When a pattern is drawa it is aligned such that adjacent areas of the same 
pattern in the same graphics port will blend with each other into a contin- 
uous, coordinated pattern. QuickDraw provides the predefined patterns wmte, 
WacK, gray, ItGiay, and dkGiay. Any other 64-bit variable or constant can be 
used as a pattern, too. The data type definition for a pattern is as follows: 

type Pattern = packed array [0..7] of 0..255; 

The row width of a pattern is 1 byte. 

EA4 Cursors 

A cursor is a small image that appears on the screen and is controlled by the 
mouse. (It appears only on the screen, and never in an off-screen bit image.) 

A cunor is defined as a 256-bit Ime^, a 16-by- 16-bit rectangle. The row 
width of a cursor is 2 bytes. Figure E-8 illustrates four cunors. 
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Figure E-8 
CXflTsors 

A cursor has three fields: a 16-worcl data field that contains the image Itself, 
a 16-word mask field that contains information about the screen appearance 
of each bit of the cursor, and a notspot point that aligns the cursor with the 
position of the mouse. 

type Cursor = record 

data: array [0..15] of integer; 
mask: array [0..15] of Integer; 
hotspot: Point 
end; 

The data for the cursor must begin on a word boundary. 

The cursor appears on the screen as a i6-by-l6-blt rectangle. The appear- 
ance of each bit of the rectangle is determined by the corresponding bits in 
the data and mask and. If the mask bit is 0, by the pixel "under" the cursor 
(the one already on the screen in the same position as this bit of the cursor) 

Data Mask Resulting pixel on screen 

White 

Black 

Same as pixel under cursor 
Inverse of pixel under cursor 

Notice that if all mask bits are o, the cursor Is completely transparent, in 
that the image under the cursor can still be viewed: pixels under the white 
part of the cursor appear unchanged, while under the black part of the cursor, 
black pixels show through as white. 

The hotspot aligns a point in the image (not a bit, a point!) with the mouse 
position. Imagine the rectangle with corners (0J3) and (16,16) framing the 
image, as in each of the examples in Figure E-8; the hotspot is defined in this 
coordinate system. A hotspot of (OJJ) is at the top left of the image. For the 
arrow in Figure E-8 to point to the mouse position, (0,0) would be its hotspot 
A hotspot of (8^) is in the exact center of the image; the center of the plus 






1 


1 


1 








1 






E-14 



Pascal Reference Manual 



QuickDraw 



sign or oval in Figure E-8 would coincide witn the mouse position if (8^) were 
the hotspot for that cursor. Similarly^ the hotspot for the pointing hand would 
be (16,9)l 

Whenever you move the mouse^ the low-level interrupt-driven mouse routines 
move the cursor's hotspot to be aligned with the new mouse position. 

QuickDraw supplies a predefined arrow cursor, an arrow pointing north- 
northwest 

Refer to Appendix F, Hardware Interface, for more information on the mouse 
and cursor control. 

E.5 The Drawing Environment: GrafPort 

A grafPort is a complete drawing environment that defines how and where 
graphic operations will have their effect. It contains all the information 
about one Instance of graphic output that is Kept separate from all other 
instances. You can have many grafPorts open at once, and each one will have 
its own coordinate system, drawing pattern, background pattern, pen size and 
location, character font and style, and bitmap in which drawing takes place. 
You can instantly switch from one port to another. GrafPorts are the 
structures on which a program builds windows, which are fundamental to the 
Lisa's "overlapping windows" user interface. 

A grafPort is a dynamic data structure, defined as follows: 



type GrafPtr = ^GrafPort; 




GrafPort = record 




device: 


integer; 


portBlts: 


Bltnap; 


portRect: 


Rect; 


visRgn: 


Rgrt^le; 


Cllp%>: 


RghHandle; 


DkPat: 


Pattern; 


flllPat: 


Pattenv 


pnLoc: 


Point; 


pnSlze: 


Point; 


pnMode: 


Integer; 


pnPat: 


Pattern; 


prtVls: 


integer; 


txFont: 


integer; 


t>4^ace: 


Style; 


txnode: 


integer; 


txSlze: 


integer; 


spExtra: 


longint; 


fgOolor: 


longint; 


bkColor: 


longint; 


colrBlt: 


int^ager; 


patstretch: 


integer; 


plcsave: 


QOHandle; 
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rgnsave: QDHandie; 

polySaive: QDHandie; 

grafProcs: OOProcsPtr 
erxt* 

All QulcKDraw operations refer to grafPorts via grafPtrs. You create a 
grafPort with the Pascal procedure new and use the resulting pointer in calls 
to QuickDraw. You could^ of course, declare a static variable of type 
GrafPort;, and obtain a pointer to that static structure (with the • operator), 
but as most grafPorts will be used dynamically, their data structures should be 
dynamic also. 

NOTE 

You can access all fields and subflelds of a grafPort normally, but you 
should not store new values directly into them. QuickDraw has 
procedures for altering all fields of a grafPort, and using these 
procedures ensures that changing a grafPort produces no unusual side 
effects. 



The device field of a grafPort is the number of the logical output device that 
the grafPort will be using. QuickDraw uses this information, since there are 
physical differences in the same logical font for different output devices. The 
default device number is 0, for the Lisa screen. 

The poortBits field is the bitmap that points to the bit Image to be used by the 
grafPort. All drawing that is done in this grafPort will take place in this bit 
image. The default bitmap uses the entire Lisa screen as its bit image, with 
rowBytes of 90 and a boundary rectangle of (0^1,720,364). The bitmap may be 
changed to Indicate a different structure in memory: all graphics procedures 
work in exactly the same way regardless of whether their effects are visible 
on the screea A program can, for example, prepare an image to be printed 
on a printer without ever displaying the image on the screen, or develop a 
picture in an off-screen bitmap before transferring it to the screen. By 
altering the coordinates of the portBits.tnund$ rectangle, you can change the 
coordinate system of the grafPort; with a QuickDraw procedure call, you can 
set an arbitrary coordinate system for each grafPort, even if the different 
grafPorts all use the same bit Image (e.g., the full screen)L 

The portRect field Is a rectangle that defines a subset of the bitmap for use 
by the grafPort Its coordinates are in the system defined by the 
portBltsixjunds rectangle. All drawing done by the application occurs Inside 
this rectangle. The portRect usually defines the "writable" Interior area of a 
window, document, or other object on the screen. The default portRect Is the 
entire screen. 

The visRgn field Indicates the region that is actually visible on the screen. It 
is reserved for use hy future software, and should be treated as read-only. 
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The default vlsRgn is set to the portRect 

The cllpRgn is an aiDitrary region that the application can use to limit 
drawing to any region within the portRect If, for example, you want to draw 
a half circle on the screen, you can set the cllpRgn to half the square that 
would enclose the whole circle, and go ahead and draw the whole circle. Only 
the half within the clipRgn will actually be drawn in the grafPort The 
default ClipRgn is set arDitrarlly large, and you have full control over its 
setting. Notice that unlike the visRgri the cllpRgn affects the image even if 
it is not displayed on the screen. 

Figure E-9 illustrates a typical bitmap (as defined by portBlts), portRect 
vlsRga and clipRgn. 
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Figure E-9 
GrafPort Regions 

The bkPat and flllPat fields of a grafPort contain patterns used by certain 
QuickDraw routines. BkPat is the "background" pattern that is used when an 
area is erased or when bits are scrolled out of it When asked to fill an area 
with a specified pattern, QuickDraw stores the given pattern in the flllPai 
field and then calls a low-level drawing routine which gets the pattern from 
that field. The various graphic operations are discussed in detail later in the 
descriptions of individual QuickDraw routines. 

Of the next ten fields, the first five determine characteristics of the graphics 
pen, described in Section E.5.1, and the last five determine characteristics of 
any text that may be drawn, described in Section E.5.2. 

The fgcolor, bkColor, and coliBlt fields contain values related to drawing in 
color, a capability that will be available in the future when Apple supports 
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color output devices for the Lisa FgColor Is the grafPort's foreground color 
and bkCoior is its background color. ColiBit tells the color imaging software 
Which plane of the color picture to draw into. For more information^ see 
Section E.7.2^ Drawing in Color. 

The patstretch field is used during output to a printer to expand patterns If 
necessary. The application should not change Its value. 

The picSave^ rgnSave^ and polySave fields reflect the state of picture^ region^ 
and polygon definition, respectively. To define a region, for example, you 
"open" it. call routines that draw It^ and then "close" It. If no region Is open. 
rgnSave contains nil- otherwise, it contains a handle to information related to 
the region definition. The application should not be concerned about exactly 
What information the handle leads to; you may. however, save the current 
value of rgnSave. set the field to nil to disable the region definition, and later 
restore It to the saved value to resume the region definition. The picsave 
and polySave fields work similarly for pictures and polygons. 

Finally, the giafProcs field may point to a special data structure that the 
application stores into if it wants to customize QuickDraw drawing procedures 
or use QuickDraw In other advanced, highly specialized ways. (For more 
Information, see Section E.10.. Customizing QuickDraw Operations.) If 
grafProcs is rtl. QuickDraw responds in the standard ways described in this 
appendix. 

E5.1 Pen CharaDteristics 

The pnLoc. pnSlze. pnMode. pnPat and pnVls fields of a grafPort deal with the 
graphics pen. Each grafPort has one and only one graphics pen. which Is used 
for drawing lines, shapes, and text As illustrated In Figure E-lO. tne pen has 
four characteristics: a locaUm a size, a drawing mo(H and a drawing pattern 
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Pattern 



Width 



Location 



Figure E-10 
AGrapmcs Pen 

The pen location (pnLoc) Is a point in the coordinate system of the grafPort, 
and is where QuickDraw will begin drawing the next line, shape, or character. 
It can be anywhere on the coordinate plane: there are no restrictions on the 
nnovement or placement of the pen. Remember that the pen location is a 
point on the coordinate plane, not a pixel in a bit Image! 

The pen is rectangular In shape, and has a user-definable width and height 
(pnslze). The default size Is a l-by-l-blt rectangle; the width and height can 
range from (0,0) to (32767,32767). If either the pen width or the pen height Is 
less than l, the pen will not draw on the screen. 

• The pen appears as a rectangle with Its top left comer at the pen 
location; it hangs below and to the right of the pen location. 

The pnMode and pnpai fields of a grafPort determine how the bits under the 
pen are affected when lines or shapes are drawn. The pnPat Is a pattern that 
Is used as the "ink" in the pen. This pattern, like all other patterns drawn In 
the grafPort, is always aligned with the port's coordinate system: the top left 
corner of the pattern Is aligned with the top left comer of the portRect, so 
that adjacent areas of the same pattern will blend Into a continuous, 
coordinated pattern. Five pattems are predefined (whlte^ black, and three 
shades of gray); you can also create your own pattem and use it as the pnPat 
(A utility procedure, called stuffHex, allows you to fill pattems easily.) 
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The pnMode field determines how the pen pattern Is to affect what's already 
on the bitmap when lines or shapes are drawn. When the pen draws, 
QuickDraw first determines what hits of the bitmap will be affected and finds 
their corresponding bits in the pattern. It then does a blt-by-bit evaluation 
based on the pen mode, which specifies one of eight boolean operations to 
perform. The resulting bit is placed into Its proper place in the bitmap. The 
pen modes are described In section E.7.1, Transfer Modes. 

The pnvis field determines the pen's visibility, that is, whether it draws on the 
screen. For more information, see the descriptions of HidePen and ShowPen 
in Section E.9.3, Pen and Llne-Drawing Routines. 

E.5.2 Text Characteristics 

The t)<Font, txFace, txMode, txsize, and spExtra fields of a grafPort determine 
how text will be drawn— the font, style, and size of characters and how they 
will be placed on the bitmap. 

QuickDraw can draw characters as quickly and easily as it draws lines and 
shapes, and in many prepared fonts. Figure E-ll shows two QuickDraw 
characters and some terms you should become familiar with, 

ascent line 



ascent 



descent 



k-^ 



character 
h- width -> 






base line 



descent line 



Figure E-ll 
QuickDraw Characters 

QuickDraw can display characters in any size, as well as boldfaced, italicized, 
outlined, or shadowed, all without changing fonts. It can also underline the 
characters, or draw them closer together or farther apart. 

The txFoni field is a font number that Identifies the character font to oe used 
In the grafPort. The font nunnber represents the system font, and Is the 
default established by OpenPort. The unit QDSupport (listed In section E.15) 
Includes definitions of other available font numbers. 

A character font is defied as a collection of bit images: these images make 
up the individual characters of the font. The characters can be of unequal 
widths, and they're not restricted to their "cells": the lower curl of a 
lowercase ], for example, can stretch back under the previous character 
(typographers call this keming). A font can consist of up to 256 distinct 
characters, yet not all characters need be defined In a single font. Each font 
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contains a missing symtx)l to be drawn in case of a request to draw a 
character that is missing from the font. 

The txFace field controls the appearance of the font with values from the set 
defined by the style data type: 

type Styleltem » (bol(t Italic^ underline^ outline^ sTiadov^ 
condense^ extend); 

style = set of Styleltenu 

You can apply these either alone or in combination (see Figure E-12). Most 
combinations usually look good only for large fonts. 

Normal Characters 
Bold Characters 

liaiia Chamcfers 
Underlined Characters xyi 



Condensed Characters 
Extended Characters 



. . . and in other fonts, too! 

Figure E-12 
Character styles 

If you specify \xm, each character is repeatedly drawn one tJit to the right an 
appropriate number of times for extra thickness. 

Italic adds an italic slant to the characters. Character bits above the toase 
line are skewed right; bits below the base line are skewed left 

Uhdenine draws a line below the base line of the characters. If part of a 
character descends below the base line (as "y" in Figure £-12), the underline is 
not drawn through the pixel on either side of the descending part. 

You may specify either ouUlne or shadow. Outline makes a hollow, outlined 
character rather than a solid one. With shadow, not only is the character 
hollow and outlined, but the outline is thickened below and to the right of the 
character to achieve the effect of a shadow. If you specify bold along with 
outline or shadow, the hollow part of the character is widened. 
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condense and extend affect tne horizontal distance between all characters. 
Including spaces. Condense decreases the distance between characters and 
extend Increases it, by an amount which QuickDraw determines is appropriate. 

The txMode field controls the way characters are placed on a bit image. It 
functions much like a pnMode: when a character is drawn, QuickDraw 
determines which bits of the bit image will be affected, does a bit-by-blt 
comparison based on the mode, and stores the resulting bits into the bit 
Image. These modes are described in Section E.7.1, Transfer Modes. Only 
three of them—srcQr, sicXor, and srcBic—should be used for drawing text 

The txsize field specifies the type size for the font, in points (where "point" 
here Is a typographical term meaning approximately 1/72 inch). Any size may 
be specified. If QuickDraw does not have the font in a specified size. It will 
scale a size it does have as necessary to produce the size desired. A value of 
in this field directs QuickDraw to choose the size from among those It has 
for the font; It will choose whichever size is closest to the system font size. 

Finally, the spExtra field is useful when a line of characters is to be drawn 
Justified such that it Is aligned with both a left and a right margin (sometimes 
called "full justification"). SpExtra Is the number of pixels by which each 
space character should be widened to fill out the line. 

E.6 Coordinates in GrafPorts 

Each grafPort has its own local coordinate system. All fields in the grafPort 
are expressed in these coordinates, and all calculations and actions performed 
in QuickDraw use the local coordinate system of the currently selected port 

Two things are important to remember: 

• Each grafPort maps a portion of the coordinate plane into a similarly- 
sized portion of a bit Image. 

• The portBltsixxjids rectangle defines the local coordinates for a grafPort 

The top left comer of portBit$.tX)unds is always aligned around the first bit in 
the bit image; the coordinates of that corner "anchor" a point on the grid to 
that bit in the bit Image. This forms a common reference point for multiple 
grafPorts using the same bit image (such as the screen). Given a 
portBits.bounds rectangle for each port, you know that their top left comers 
coincide. 

The Interrelationship between the portBitsJxxinds and portRect rectangles is 
very important As the portBitsJaounds rectangle establishes a coordinate 
system for the port, the portRect rectangle indicates the section of the 
coordinate plane (and thus the bit image) that will be used for drawing. The 
portRect usually falls Inside the portBit$.bounds rectangle, but it's not required 
to do so. 

When a new grafPort is created. Its bitmap is set to point to the entire Lisa 
screen, and both the portBitslxiunds and the portRect rectangles are set to 
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720-by-364-Dlt rectangles, with the point (0,0) at the top left corner of the 
screen. 

You can redefine the local coordinates of the top left corner of the grafPorfs 
portRect, using the SetOrigln procedure. This changes the local coordinate 
system of the grafPort, recalculating the coordinates of all points in the 
grafPort to t)e relative to the new comer coordinates. For example, consider 
these procedure calls: 

SetPort(gaiiBPort); 
Set0rigin(40,80); 

The call to SetPort sets the current grafPort to gamePort; the call to 
setorlgin changes the local coordinates of the top left corner of that port's 
portRect to (40,80) (see Figure E-i3). 




visRgn (95,120)(300j275) 
clipRgn (95,120X300,275) 

Before SetOrigin 



visRgn (4a80)(245,235) 
ClipRgn (95,120X300,275) 

After S8tOrigin(4Ci,80) 



Figure E-13 
Changing Local Coor(flnates 

This recalculates the coordinate components of the following elements: 

gaiiiBPort * .portBlts .Dounds ganieport " .portRect 

gairiePort* -VisRgn 

These elements are always kept "in sync", so that all calculations, compari- 
sons, or operations that seem right, work right. 

Notice that when the local coordinates of a grafPort are offset, the vlsRgn of 
that port is offset also, but the clipRgn is not, A good way to think of it is 
that if a document is being shown inside a grafPort, the document "sticks" to 
the coordinate system, and the port's structure "sticks" to the screen. 
Suppose, for example, that the visRgn and clipRgn in Figure E-13 before 
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SetQrlgin are the sarme as the portRect and a document Is being shown. After 
the SetOrigin call, the top left comer of the cUpRgn is still (95J.20), but this 
location has moved down and to the right, and the location of the pen within 
the document has similarly moved. The locations of portBltsixxjids, portRect, 
and vlsRgn did not change; their coordinates were offset As always, the top 
left comer of portBltsJaounds remains aligned around the first bit in the bit 
image (the first pixel on the screenX 

If you are moving, comparing, or otherwise dealing with mathematical items In 
different grafPorts (for example, finding the Intersection of two regions in two 
different grafPorts), you must adjust to a comnnon coordinate system before 
you perform the operation. A QuickDraw procedure. Local ToGlobal, lets you 
convert a point's local coordinates to a global system where the top left 
corner of the bit image Is (0,0); by converting the various local coordinates to 
global coordinates, you can compare and mix them with confidence. For more 
information, see the description of this procedure In Section E.9.17, 
Calculations with Points. 

E.7 General Discussion of Drawing 

Drawing occurs: 

• Always inside a grafPort, In the bit Image and coordinate system defined 
by the grafPort's bitmap. 

• Always within the intersection of the grafPort's portBlts.bound$ and 
portRect, and clipped to its visRc^ and olipRgn. 

• Always at the grafPort's pen location. 

• Usually with the grafPort's pen size, pattern, and mode. 

With QuickDraw procedures, you can draw lines, shapes, and text. Shapes 
include rectangles, ovals, rounded-corner rectangles, wedge-shaped sections of 
ovals, regions, and polygons. 

Lines are defined by two points: the current pen location and a destination 
location. When drawing a line, QuickDraw moves the top left corner of the 
pen along the mathematical trajectory from the current location to the 
destination. The pen hangs below and to the right of the trajectory (see 
Figure E-14). 
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Figure E-14 
Drawing Lines 

NOTE 



No mathematical element (such as the pen location) is ever affected by 
clipping; clipping only determines what appears where In the bit image. 
If you draw a line to a location outside your grafPort^ the pen location 
will move there^ but only the portion of the line that is inside the port 
will actually be drawn. This is true for all drawing procedures. 



Rectangles, ovals, and rounded-comer rectangles are defined by two comer 
points. The shapes always appear inside the mathematical rectangle defined 
by the two points. A region is defined In a more complex manner, but also 
appears only within the rectangle enclosing it. Remember, these enclosing 
rectangles have infinitely thin borders and are not visible on the screen. 

As illustrated in Figure E-15^ shapes may be drawn either solid (filled in with 
a pattern) or framed (outlined and hollow). 
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Figure E-15 
Solid Shapes and Framed Shapes 

In the case of framed shapes^ the outline aooears completely within the 
enclosing rectangle—with one exception—arid the vertical and horizontal 
thickness of the outline Is determined hy the pen size. The exception Is 
polygons^ as discussed In section E.8.2^ Polygons. 

The pen pattern is used to fill In the hits that are affected by the drawing 
operation. The pen mode defines how those bits are to be affected by 
directing QuickDraw to apply one of eight boolean operations to the bits in 
the shape and the corresponding pixels on the screen. 

Text drawing does not use the pnsize, pnPat^ or pnMooe^ but It does use the 
pnLoa Each character is placed to the right of the current pen location, with 
the left end of Its base line at the pen's location. The pen is moved to the 
right to the location where It will draw the next character. No wrap or 
carriage return is performed automatically. 

The method QuickDraw uses In placing text is controlled by a mode similar to 
the pen mode. This is explained in Section E.7.1, Transfer Modes. Clipping of 
text Is performed in exactly the same manner as ail other clipping in 
QuickDraw, 

EJ.1 Transfer Mooes 

When lines or shapes are drawn, the pnMode field of the grafPort determines 
how the drawing is to appear in the port's bit image; similarly, the txMode 
field determines how text Is to appear. There is also a QuickDraw procedure 
that transfers a bit image from one bitmap to another, and this procedure has 
a mode parameter that determines the appearance of the result. In all these 
cases, the mode, called a transfer mocH specifies one of eight boolean 
operations: for each bit in the Item to be drawn, QuickDraw finds the 
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corresponding bit In tne destination bit Image^ performs the boolean operation 
on the pair of bits, and stores the resulting bit into the bit image. 

There are two types of transfer mode: 

• Pattern transfer mocfas, for drawing lines or shapes with a pattern. 

• source transfer modesi for drawing text or transferring any bit image 
between two bitmaps. 

For each type of mode, there are four basic operations— Copy, or, xor. and 
Bi& The Copy operation simply replaces the pixels in the destination with 
the pixels In the pattern or source, "painting" over the destination without 
regard for what is already there. The Or, Xor, and Bic operations leave the 
destination pixels under the white part of the pattern or source unchanged, 
and differ in how they affect the pixels under the black part: Or replaces 
those pixels with black pixels, thus "overlaying" the destination with the black 
part of the pattern or source; Xor Inverts the pixels under the black part; and 
Blc erases them to white. 

Each of the basic cperatlons has a variant in which every pixel in the pattern 
or source Is Inverted before the operation is performed, giving eight 
operations in all. Each mode is defined by name as a constant In GJuickDraw 
(see Figure E-16)i 







pattern or ^owce destination 

"Paint" "Overlay" "Invert" "Erase" 



patCopy 
srcCopy 




srcO 



patXcf 
srcXcf 



patBIc 
srcBic 



HM mm 



iini 



notPatCopy notPatOr notPatXor notPatBlc 
notSrcCopy notSrcOr notSrcXor notSrcBic 

Figure E-16 
Transfer Modes 
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Pattern source 
transfer transfer 
mode nnode 



Action on each pixel in destination: 
If black pixel in if white pixel in 
pattern or source pattern or source 



patcopy 
palOr 
patxor 
patBic 

notPatcopy 
notPaiGr 
notPatXor 
notPatBic 


srccopy 
srcOr 
srcxor 
srcBic 

notsrccopy 
notsrcor 
noisrcxor 
notSrcBic 


Force black 
Force black 
Invert 
Force white 

Force white 
Leave alone 
Leave alone 
Leave alone 


Force white 
Leave alone 
Leave alone 
Leave alone 

Force black 
Force black 
Invert 
Force white 



E.7.2 Drawing in Color 

Currently you can only look at QuickDraw output on a black-and-white screen 
or printer. Eventually^ however, Apple will support color output devices. If 
you want to set up your application now to produce color output in the future, 
you can do so by using QuickDraw procedures to set the foreground color and 
the background color. Eight standard colors may be specified with the 
following predefined constants: blackColor, whlteColor, redColor, greenColor, 
bluecolor, cyancolor, magentaColor, and yellowcolor. Initially, the foreground 
color is blackColor and the background color is whiteColor. If you specify a 
color other than whiteColor, it will appear as black on a black-and-white 
output device. 

To apply the table above (in Section E.7.1) to drawing in color, make the 
following translation: where the table shows "Force black", read "Force 
foreground color", and where it shows "Force whlte"^ read "Force background 
color". When you eventually receive the color output device, you'll find out 
the effect of inverting a color on It. 

NOTE 

QuickDraw can support output devices that have up to 32 bits of color 
Information per pixel. A color picture may be thought of, then, as 
having up to 32 planes. At any one time, QuickDraw draws Into only 
one of these planes. A QuickDraw routine called by the color-Imaging 
software specifies which plane. 

E.8 Pictures and Polygons 

QuickDraw lets you save a sequence of drawing commands and "play them 
back" later with a single procedure call. There are two such mechanisms: one 
for drawing any picture to scale in a destination rectangle that you specify, 
and another for drawing polygons in all the ways you can draw other shapes in 
QuickDraw. 



E-28 



Pascal Reference Manual QuickDraw 



EAl Pictures 

A picture in QuickDraw is a transcript of calls to routines which draw 
somethlng~anythlng~on a bitmap. Pictures make it easy for one program to 
draw something defined In another program^ with great flexidillty and without 
knowing the details about whafs being drawn. 

For each picture you define, you specify a rectangle that surrounds the 
picture; this rectangle Is called the picture frame When you later call the 
procedure that draws the saved picture, you supply a destination rectangle, 
and QuickDraw scales the picture so that its frame Is completely aligned with 
the destination rectangle. Thus, the picture may be expanded or shrunk to fit 
Its destination rectangle. For example. If the picture Is a circle Inside a 
square picture frame, and the destination rectangle Is not square, the picture 
Is drawn as an oval. 

Since a picture may include any sequence of drawing commands, its data 
structure is a variable-length entity. It consists of two fixed fields followed 
by a variable-length data field: 

type Picture = record 

plcSlze: Integer; 
plcFrame: Rect; 
{picture definition data} 
erxt* 

The picSIze field contains the size, in bytes, of the picture variable. The 
plcFrame field Is the picture frarro which surrounds the picture and gives a 
frame of reference for scaling when the picture Is drawn. The rest of the 
structure contains a compact representation of the drawing commands that 
define the picture. 

All pictures are accessed through handles, which point to one master pointer 
which In turn points to the picture. 

type PicPtr = Tlcture; 
PlcHandle = TicPtr; 

To define a picture, you call a QuickDraw function that returns a picture 
handle and then call the routines that draw the picture. There Is a procedure 
to call when you've finished defining the picture, and another for when you're 
done with the picture altogether. 

QuickDraw also allows you to intersperse 0cture comments with the 
definition of a picture. These comments, which do not affect the picture's 
appearance, may be used to provide additional information about the picture 
when It's played back. This is especially valuable when pictures are 
transmitted from one application to another. There are two standard types of 
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comment which, like parentheses, serve to group drawing commands together 
(such as all the commands that draw a particular part of a picture) 

const plcLParen = 0; 
plcRParen = l; 

The application defining the picture can use these standard comments as well 
as comments of its own desiga 

To Include a conr>ment in the definition of a picture, the application calls a 
QuickDraw procedure that specifies the comment with three parameters: the 
comment kind, which identifies the type of comment; a handle to additional 
data if desired; and the size of the additional data, if any. When playing back 
a picture, QuickDraw passes any comments in the picture's definition to a 
low-level procedure accessed indirectly through the grafProcs field of the 
grafPort (see Section E.lO, Customizing QuickDraw operations, for more 
information). To process comments, the application must include a procedure 
to do the processing and store a pointer to it in the data structure pointed to 
by the grafProcs field. 

NOTE 

The standard low-level procedure for processing picture comments 
simply ignores all comrments. 

E.a2 Polygons 

Polygons are similar to pictures in that you define them by a sequence of 
calls to QuickDraw routines. They are also similar to other shapes that 
QuickDraw knows about, since there is a set of procedures for performing 
graphic operations and calculations on them. 

A polygon is simply any sequence of connected lines (see Figure E-17). You 
define a polygon by moving to the starting point of the polygon and drawing 
lines from there to the next point, from that point to the next, and so on. 




Figure E-17 
Polygons 
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me data structure for a polygon Is a varlabie-iengtn entity, it consists of 
two fixed fields followed by a variable-length array: 

type Polygon = record 

polySlze: Integer; 
polyBBox: Rect; 
polyPoints: array [0..0] of Point 
end; 

Tne polySlze field contains the size, in bytes^ of the polygon variable. The 
pdlyBBox field Is a rectangle which just encloses the entire polygon. The 
poiyPolnts array expands as necessary to contain the points of the polygon— 
the starting point followed ty each successive point to which a line is drawn. 

Like pictures and regions^ polygons are accessed through handles. 

type PolyPtr = "Polygon; 
PolyHandle = ^PolyPtr; 

To define a polygon, you call a QuickDraw function that returns a polygon 
handle and then form the polygon Xiy calling procedures that draw lines. You 
call a procedure when you've finished defining the polygon, and another when 
you're done with the polygon altogether. 

Just as for other shapes that QuickDraw knows about, there is a set of 
graphic operations on polygons to draw them on the screen. QuickDraw draws 
a polygon by moving to the starting point and then drawing lines to the 
remaining points in succession, just as when the routines were called to define 
the polygon. In this sense it "plays back" those routine calls. As a result, 
polygons are not treated exactly the same as other QuickDraw shapes. For 
example, the procedure that frames a polygon draws outside the actual 
boundary of the polygon, because QuickDraw line-drawing routines draw below 
and to the right of the pen location. The procedures that fill a polygon with 
a pattern, however, stay within the boundary of the polygon; they also add an 
additional line between the ending point and the starting point if those points 
are not the same, to complete the shape. 

There is also a difference in the way QuickDraw scales a polygon and a 
similarly-shaped region if it's being drawn as part of a picture: when 
stretched, a slanted line is drawn more smoothly if it's part of a polygon 
rather than a region. You may find it helpful to keep in mind the conceptual 
difference between polygons and regions: a polygon is treated more as a 
continuous shape, a region more as a set of bits. 

E.9 QuickDraw Routines 

This section describes all the procedures and functions In QuickDraw, their 
parameters, and their operation. They are presented In their Pascal form; for 
information on using them from assembly language, see Section E.ll, Using 
QuickDraw from Assembly Language. Note that the actual procedure and 
function declarations are given here, rather than the BNF notation or syntax 
diagrams used elsewhere in this manual. 
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E.9.1 GrafPort Routines 

Procedure InltGraf (globalPtr: QDPtr); 

InliGraf initializes QuickDraw. It is called by the QDSupport unit's GJDlnit 
routine; you need not call It again, it initializes the QuickDraw global 
variables listed below. 



variable 


Type 
GrafPtr 


Initial settlna 


thePort 


nil 


white 


Pattern 


all-white pattern 


black 


Pattern 


all-black pattern 


gray 


Pattern 


50% gray pattern 


itGray 


Pattern 


25% gray pattern 


dkGray 


Pattern 


75% gray pattern 


arrow 


Cursor 


pointing arrow cursor 


screenBits 


Blthap 


Lisa screen, (0,0,720^64) 


randSeed 


longlnt 


1 



The globalPtr parameter tells QuickDraw where to store its global variables, 
beginning with thePort From Pascal programs, this parameter should always 
be set to stnePort; assennbly-language programmers may choose any location, 
as long as it can accommodate the number of bytes specified by GRAFSIZE in 
GR/NFTYPES.TEXT (see Section E.ll, using QuickDraw from Assembly 
Language). 

NOTE 

To initialize the cursor, call initCursor (described in section E.9.2, 
Cursor-Handling Routines). 



Procedure OpenPort (gp: GrafPtr); 

qpenPort allocates space for the given grafPorfs vlsRgn and cllpRgn, 
initializes the fields of the grafPort as indicated below, and makes the 
grafPort the current port (see SetPort, below)L You must call OpenPort before 
using any grafPort; first create a grafPtr with new, then use that grafPtr in 
the OpenPort call. 
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Field 


Type 


Initial settlm 


device 


integer 


(Lisa screen) 


portSlts 


Bltnap 


screenBlts (see initGraf) 


portRect 


Rect 


screenBltsiwunds (0A720364) 


vlsRgn 


RgnHandle 


handle to the rectangular region (0^720364) 


clipRgn 


RgnHandle 


handle to the rectangular region 
(-30000, -30000, 30000, 30000) 


bkPat 


Pattern 


White 


flllPat 


Pattern 


black 


pnLoc 


Point 


(0J3) 


pnsize 


Point 


(LI) 


pnhode 


integer 


patcopy 


pnpat 


Pattern 


black 


pnVis 


integer 


(visible) 


txFont 


Integer 


(system font) 


t>4^aDe 


style 


normal 


txnode 


Integer 


srcnr 


txsize 


integer 


(QuickDraw decides) 


spExtra 


longlnt 





fgcolor 


longint 


biackcoior 


bkcolor 


longlnt 


whlteCX)ior 


COlTBlt 


Integer 





patstretch 


Integer 





plcsave 


QOHandle 


nil 


rgnsave 


QDHandle 


nil 


polySave 


QDHandle 


nil 


grafProcs 


QDProcsPtr 


nil 



Procedure InitPort (gp: GrafPtr); 

Given a pointer to a grafPort that has been opened with openPort, inltPort 
reinitializes the fields of the grafPort and makes it the current port (if it's 
not already). 

NDTTE 

InitPort does everything OpenPort does except allocate space for the 
visRgn and clipRgn. 



Procedure ClosePort (gp: GrafPtr); 

ClosePort deallocates the space occupied by the given grafPort's visRgn and 
clipRga When you are completely through with a grafPort^ call this 
procedure. 
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WARNINGS 

If you do not call closePort before disposing of the grafPort, the 
memory used by the visRgn and clipRgn will be unrecoverable. 

After calling ClosePort, be sure not to use any copies of the vlsRgn or 
ClipRgn handles that you may have made. 



Procedure SetPort (gp: GrafPtr); 

setPort sets the grafPort Indicated by gp to be the current port. The global 
pointer thePort always points to the current port. All QuickDraw drawing 
routines affect the bitmap thePon'^xMftBlts and use the local coordinate 
system of thePort". Note that OpenPort and InitPort do a SetPort to the 
given port. 

WARNING 

Never do a SetPort to a port that has not been opened with OpenPort. 

Each port possesses its own pen and text characteristics which remain 
unchanged when the port is not selected as the current port 

Procedure GetPort (var gp: GrafPtr); 

GetPort returns a pointer to the current grafPort. If you have a program that 
draws into more than one grafPort, it's extremely useful to have each 
procedure save the current grafPort (with GetPort), set its own grafPort, do 
drawing or calculations, and then restore the previous grafPort (with SetPort). 
The pointer to the current grafPort is also available through the global 
pointer thePort, but you may prefer to use GetPort for better readability of 
your program text. For example, a procedure could do a GetPort(savePort) 
before setting Its own grafPort and a SetPort($avePort} afterwards to restore 
the previous port 

Procedure Graf Device (device: Integer); 

GrafDevlce sets thePort ".device to the given number, which Identifies the 
logical output device for this grafPort QuickDraw uses this Information. The 
Initial device number Is 0, which represents the Lisa screen. 

Procedure SetPortBlts (bm: BltHap); 

SetPortBlts sets thePort ".portBlts to any previously defined bitmap. This 
allows you to perform all normal drawing and calculations on a buffer other 
than the Lisa screen—for example, a 640-by-8 output buffer for a dot matrix 
printer, or a small off-screen image for later "stamping" onto the screen. 
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Rememder tx) prepare all fields of ine bitmap Defore you call setPortBlts. 

Procedure PortSize (•idth, height: Integer); 

PortSlze changes the size of the current grafPort's portRect mJs aaes not 
affect the screen; it merely changes the size of the "active area" of the 
grafPort 

The top left comer of the portRect remains at its same location; the width 
and height of the portRect are set to the given width and height In other 
words^ PortSize moves the bottom right comer of the portRect to a position 
relative to the top left comer. 

PortSize does not change the cllpRgn or the vlsRgn. nor does it affect the 
local coordinate system of the grafPort: it changes only the portRect's width 
and height Rememder that all drawing occurs only in the Intersection of the 
portBitsJxiunds and the portRect clipped to the visRgn and the cllpRga 

Procedure hovePortTo (leftGlobal^topGlobal: Integer); 

MovePortTo changes the position of the current grafPort's portRect This aces 
not affect the screen; it merely changes the location at which subsequent 
drawing inside the port will appear. 

The leftGlobal and topGlobal parameters set the distance between the top left 
comer of the portBitsixxjnds and the top left corner of the new portRect 
For example^ 

riovePortTo(360. 182); 

will move the top left comer of the portRect to the center of the screen (if 
portBits is the Lisa screen) regardless of the local coordinate system. 

Like PortSize, MovePortTo does not change the cllpRgn or the vlsRgn, nor 
does it affect the local coordinate system of the grafPort 

Procedure SetOrlgln (h,v: Integer); 

SetOrigin changes the local coordinate system of the current grafPort This 
does not affect the screeh;\i does, however, affect where subsequent drawing 
and calculation will appear in the grafPort SetOrlgln updates the coordinates 
of the portBltsiMunds, the portRect and the vlsRgn. All subsequent drawing 
and calculation routines will use the new coordinate system. 

The ri and V parameters set the coordinates of the top left comer of the 
portRect All other coordinates are calculated from this point All relative 
distances among any elements In the port will remain the same; only their 
absolute local coordinates will change. 
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NOTE 

SetOrlgln does not update the coordinates of the clipRgn or the pen; 
these items stick to the coordinate system (unlike the port's structure, 
which sticks to the screen). 

SetOrlgln Is useful for adjusting the coordinate system after a scrolling 
operation. (See scrollRect in Section E.9.13, Bit Transfer Operations.) 

Procedure SetCllp (rgn: RgnHandle); 

SetClip changes the clipping region of the current grafPort to a region 
equivalent to the given region. Note that this does not change the region 
handle, but affects the clipping region itself. Since SetClip makes a copy of 
the given region, any suDsequent changes you make to that region will not 
affect the clipping region of the port 

You can set the clipping region to any arbitrary region, to aid you in drawing 
Inside the grafPort. The initial clipRgn is an arOitrarlly large rectangle. 

Procedure l^tcilp (rgn: Rgrtfendle); 

CSetCllp changes the given region to a region equivalent to the clipping region 
of the current grafPort. This is the reverse of what SetCllp does. Like 
SetClip, it does not change the region handle. 

Procedure CllpRect (r: Rect); 

ClipRect changes the clipping region of the current grafPort to a rectangle 
equivalent to given rectangle. Note that this does not change the region 
handle, but affects the region itself. 

Procedure BackPat (pat: Pattern); 

BackPat sets the background pattern of the current grafPort to the given 
pattern. The background pattern is used in ScrollRect and in all QuickDraw 
routines that perform an "erase" operation. 

E.9.2 Cunor-Handllng Routines 

Additional information on cursor handling can be found in Appendix F, 
Hardware Interface. 

Procedure InitCursor; 

InltCursor sets the current cursor to the predefined arrow cursor, an arrow 
pointing north-northwest, and sets the cursor level to 0, making the cursor 
visible. The cursor level, which Is Initialized to when the system is booted, 
keeps track of the number of times the cursor has been hidden to compensate 
for nested calls to HideOursor and ShowCursor (below). 
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Before you call inltCursor^ the cursor is undefined (or, if set by a previous 
process. It's whatever that process set It to). 

Procedure SetCursor (crsr: cursor); 

SetCursor sets the current cursor to the le-by- 16-bit Image In crsr. If the 
cursor is hidden, it remains hidden and will attain the new appearance when 
it's uncovered; if the cursor is already visible, it changes to the new 
appearance immediately. 

The cunor image is initialized by InitCursor to a north-northwest arrow, 
visible on the screen. There is no way to retrieve the current cursor image. 

Procedure HideCursor; 

HideCursor removes the cursor from the screen, restoring the bits under it, 
and decrements the cursor level (which InitCursor initialized to 0). Every call 
to HideCursor should be balanced by a subsequent call to Showcursor. 

Procedure ShonCursor; 

Showcursor increments the cursor level, which may have been decremented by 
HideCursor, and displays the cunor on the screen If the level becomes 0. A 
call to Showcursor should balance each previous call to HideCursor. The 
level is not incremented beyond 0, so extra calls to Showcursor don't hurt. 

If the cursor has been changed (with SetCursor) while hidden, Showcursor 
presents the new cursor. 

The cursor is initialized by InitCursor to a north-northwest arrow, not hidden. 

Procedure ObscureCursor; 

ObscureCursor hides the cursor until the next time the mouse is moved. Unlike 
HideCursor, it has no effect on the cursor level and must not be balanced by 
a call to Showcursor. 

E.9.3 Pen and Une-Drawlng Routines 

The pen and line-drawing routines all depend on the coordinate system of the 
current grafPort. Remember that each grafPort has its own pen; if you draw 
In one grafPort, change to another, and return to the first the pen will have 
remained in the same location. 

Procedure HldePen; 

HidePen decrements the current grafPort's pnVls field, which is initialized to 
by OpenPort; whenever pnVls is negative, the pen does not draw on the 
screen. PnVls keeps track of the number of times the pen has been hidden to 
compensate for nested calls to HidePen and ShowPen (below). HidePen is . 
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called by OpenRgn, OpenPIcture, and ppenPoly so that you can define regions, 
pictures^ and polygons without drawing on the screen. 

Procedure ShovPen; 

ShowPen increments the current grafPort's pnvis fields which may have been 
decremented Dy HIdePen; If pnVls becomes 0, QuickDraw resumes drawing on 
the screen. Extra calls to ShowPen will increment pnVls beyond 0, so every 
call to ShowPen should be balanced by a subsequent call to HldePen. 
ShowPen is called by CloseRgn^ ClosePicture, and ClosePoly. 

Procedure GetPen (var pt: Point); 

GetPen returns the current pen location, in the local coordinates of the 
current grafPort 

Procedure GetPenState (var pnstate: PenState); 

GetPenstate saves the pen location, size, pattern, and mode In a storage 
variable, to be restored later with SetPenState (below). This is useful when 
calling short subroutines tJiat operate In tDe current port but must change tJie 
graphics pen: each such procedure can save the pen's state when it's called, do 
whatever it needs to do, and restore the previous pen state Immediately 
before returning. 

The PenState data type is not useful for anything except saving the pen's 
state. 

Procedure SetPenState (pnstate: PenState); 

SetPenState sets the pen location, size, pattern, and mode in the current 
grafPort to the values stored in pnStata This is usually called at the end of 
a procedure that has altered the pen parameters and wants to restore them to 
their state at the beginning of the procedure. (See GetPenState, above.) 

Procedure PenSize (width, height: integer); 

PenSize sets the dimensions of the graphics pen in the current grafPort. All 
subsequent calls to Line, LineTo, and the procedures that draw framed shapes 
in the current grafPort will use the new pen dimensions. 

The pen dimensions can be accessed in the variable thePort''4)nSlze, which Is 
of type Point If either of the pen dimensions is set to a negative value, the 
pen assumes the dimensions (0,0) and no drawing Is performed. For a 
discussion of how the pen draws, see Section E.7, General Discussion of 
Drawing. 
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Procedure PenMode (mode: Integer); 

PenMode sets the transfer mode through which the pnPat Is transferred onto 
the bitmap when lines or shapes are drawn. The mode may be any one of the 
pattern transfer modes: 

patOopy patxor notPatOopy notPatXor 

pator patsic notPator notPatBlc 

If the mode is one of the source transfer modes (or negative^ no drawing is 
performed. The current pen mode can be obtained in the variable 
thePort*4)nMode. The Initial pen mode is patcopy, in which the pen pattern 
is copied directly to the bitmap. 

Procedure PenPat (pat: Pattern); 

PenPat sets the pattern that is used by the pen in the current grafPort. The 
standard patterns white^ blacK/ gray^ Itcaray, and dkGray are predefined; the 
initial pen pattern is blade The current pen pattern can be obtained in the 
variable thePort"4)nPaC and this value can be assigned (but not compared!) to 
any other variable of type Pattern. 

Procedure PenNomel; 

PenNormal resets the initial state of the pen in the current grafPort, as 
follows: 

Field Setting 

pnSlze (O) 

pnHode patcopy 

pnPat black 

The pen location is not changed. 

Procedure rtovelo (h,v: Integer); 

MoveTo moves the pen to location (h,v) in the local coordinates of the current 
grafPort. No drawing is performed. 

Procedure hove (dh,dv: integer); 

Move moves the pen a distance of dh horizontally and dv vertically from its 
current location; it calls MoveTo(h+dh,v+dvX where (h,v) is the current location. 
The positive directions are to the right and down. No drawing is performed. 
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Procedure LlneTo (r\,v: integer); 

LineTo draws a line from the current pen location to the location specified (In 
local coordinates) by h and v. The new pen location Is (Tvv) after the line Is 
drawn. See Section E.7^ General Discussion of Drawing. 

If a region or polygon is open and being formed. Its outline is infinitely thin 
and Is not affected by the pnsize, pnMode, or pnpat (See openRgn ana 
OpenPoly.) 

Procedure Line (dh,dv: integer); 

Line draws a line to the location that is a distance of dh horizontally and dv 
vertically from the current pen location; it calls LineTo(h+dnv+dvX where (h,v) 
Is the current location. The positive directions are to the right and down. 
The pen location becomes the coordinates of the end of the line after the line 
is drawn. See Section E.7, General Discussion of Drawing. 

If a region or polygon is open and being formed. Its outline Is Infinitely thin 
and Is not affected by the pnSize, pnMode, or pnPat (See OpenRgn and 
OpenPoly.) 

E.9.4 Text-Drawing Routines 

Each grafPort has its own text characteristics, and all these procedures deal 
with those of the current port. 

Procedure TextFont (font: integer); 

TextFont sets the current graf Port's font (thePort".t)tf^onl) to the given font 
number. The initial font number Is 0, which represents the system font. For 
other font numbers, refer to the QDSupport unit, listed In Section E.15. 

Procedure TextFace (face: Style); 

TextFace sets the current grafPorfs character style (thePorl'.txFace). The 
Style data type allows you to specify a set of one or more of the following 
predefined constants: bold, Italic, underline, outline, shadow, condense, and 
extend. For example: 

TextFace( [bold] ); {bold} 

TextFace( [bold, italic]); {bold and italic} 

TextFace(thePort*.txFace+[boldl); {ihatever it was plus bold} 

TextFace(thePort*.txFace-[boldj); {whatever it was but not bold} 

TextFace( [ ] ); {normal } 
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Procedure Textnocie (mode: Integer); 

TextMode sets the current grafPort's transfer mode for drawing text 
(thePort".txMode). The mode should De srcoo srcXor^ or srcBic. The initial 
transfer mode for drawing text is srcor. 

Procedure TextSlze (size: Integer); 

Textslze sets the current grafPort's type size (thePort".txSlze) to the given 
number of points. Any size may l3e specified^ but the result will look best if 
QuickDraw has the font in that size (otherwise it will scale a size it does 
haveX The next best result will occur if the given size is an even multiple of 
a size available for the font. If o is specified, QuickDraw will choose one of 
the available sizes—whichever is closest to the system font size. The initial 
txSize setting is a 

Procedure SpaceExtra (extra: Integer); 

SpaceExtra sets the current grafPort's spExtra field, which specifies the 
number of pixels by which to widen each space in a line of text This is 
useful when text is being fully Justified (that is, aligned with both a left and a 
right margin). Consider, for example, a line that contains three spaces; if 
there would normally be six pixels between the end of the line and the right 
margin, you would call SpaceExtra(2) to print the line with full Justification. 
The initial spExtra setting is 0. 

NOTE 

SpaceExtra will also take a negative argument, but be careful not to 
narrow spaces so much that the text is unreadabla 



Procedure DravChar (ch: char); 

DrawChar places the given character to the right of the pen location, with 
the left end of its base line at the pen's location, and advances the pen 
accordingly. If the character is not in the font, the font's missing symbol is 
drawn. 

Procedure Orai»Strlng (s: strZ55); 

Drawstring performs consecutive calls to DrawChar for each character in the 
supplied string; the string is placed beginning at the current pen location and 
extending right No formatting (carriage returns, line feeds, etc.) is performed 
by QuickDraw. The pen location ends up to the right of the last character in 
the string. 
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Procedure DraiText (textaif : OOPtr; flrstByte^DyteCount: Integer); 

DrawText draws text from an artoltrary structure In memory specified by 
textBuf, starting flrslByte bytes into the structure and continuing for 
bytecount bytes. The string of text is placed beginning at the current pen 
location and extending right. No formatting (carriage returns^ line feeds^ etc.) 
Is performed by GJulckDraw. The pen location ends up to the right of the last 
character in the string. 

Function CharVldth (ch: char) : integer; 

CharWidth returns the value that will be added to the pen horizontal 
coordinate if the specified character is drawn. Charwidth includes the effects 
of the stylistic variations set with TextFace; if you change these after 
determining the character width but before actually drawing the character, 
the predetermined width may not be correct. If the character Is a space, 
CharWidth also Includes the effect of SpaceExtra. 

Function stringvidtn (s: Str255) : integer; 

Stringwldth returns the width of the given text string, which it calculates by 
adding the widths of all the characters In the string (see Charwidth, above)!' 
This value will be added to the pen horizontal coordinate if the specified 
string Is drawn. 

Function Textiidth (textBuf : QOPtr; firstByte^byteCount: integer) : 
integer; 

TextWldth returns the width of the text stored in the arbitrary structure In 
memory specified by textBuf, starting flrstByte bytes Into the structure and 
continuing for byteCount bytes. It calculates the width by adding the widths 
of all the characters In the text. (See CharWidth, above.) 

Procedure GetFontlnfo (var info: Fontlnfo); 

GetFontlnfo returns the following information about the current grafPort's 
character font, taking Into consideration the style and size in which the 
characters will be drawn: the ascent, descent, maximum character width (the 
greatest distance the pen will move when a character is drawn), and leading 
(the vertical distance between the descent line and the ascent line below It), 
all in pixels. The Fontlnfo data structure Is defined as: 

type Fontlnfo = record 

ascent: integer; 
descent: integer; 
vidhax: integer; 
leading: integer 
end; 
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E.95 Drawing in color 

These routines will enable applications to do color drawing in tne future when 
Apple supports color output devices for the Lisa All nonwhite colors will 
appear as Plack on Dlack-and-white output devices. 

Procedure ForeOolor (color: longlnt); 

Forecolor sets the foreground color for all drawing in the current grafPort 
(thePort".fgColor) to the given color. The following standard colors are 
predefined: OlackColor^ whiteColoL redColor, greenColor, blueColor^ cyanColor^ 
magemaCX)lor^ and yeliowcolor. The initial foreground color is biackcolor. 

Procedure BackCoior (color: longlnt); 

Backcolor sets the background color for all drawing in the current grafPort 
(thePort''i)kCoior) to the given color. Eight standard colors are predefined 
(see Forecolor, above> The initial background color is wmtecolor. 

Procedure ColorBit (ihichBit: integer); 

ColorBlt is called by printing software for a color prlnteL or other color- 
imaging software, to set the current grafPort's colrBlt field to whlchBlt; this 
tells QuickDraw which plane of the color picture to draw into. QuickDraw 
will draw into the plane corresponding to bit number whlchBit Since 
QuickDraw can support output devices that have up to 32 bits of color 
information per pixel, the possible range of values for whichBlt is through 
31. The initial value of the colrBit field is 0. 

E.9.6 Calculations with Rectangles 

Calculation routines are Independent of the current coordinate system; a 
calculation will operate the same regardless of which grafPort is active. 

NtTFE 

Remember that if the parameters to one of the calculation routines 
were defined in different grafPorts, you must first adjust them to be in 
the same coordinate system. If you do not adjust them, the result 
returned by the routine may be different from what you see on the 
screen. To adjust to a common coordinate system, see LocalToGlobal 
and GlobalToLocal In Section E.9.17, Calculations with Points. 

Procedure SetRect (var r: Rect; left, top, right, bottom: Integer); 

SetRect assigns the four boundary coordinates to the rectangle. The result is 
a rectangle with coordinates (left,topjrt^tjDottom). 

This procedure is supplied as a utility to help you shorten your program text. 
If you want a more readable text at the expense of length, you can assign 
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Integers (or points) directly Into the rectangle's fields. There Is no significant 
code size or execution speed advantage to either method; one's just easier to 
write, and the other's easier to read. 

Procedure CJffsetRect (var r: Rect; drvdv: integer); 

OffsetRect moves the rectangle by adding dh to each horizontal coordinate 
and dv to each vertical coordinate. If dh and dv are positive, the movement 
Is to the right and down; If either Is negative, the corresponding movement is 
in the opposite direction. The rectangle retains Its shape and size; It's merely 
moved on the coordinate plane. This does not affect the screen unless you 
subsequently call a routine to draw within the rectangle. 

Procedure InsetRect (var r: Rect; dtvdv: integer); 

InsetRect shrinks or expands the rectangle. The left and right sides are 
moved In by the amount specified by dh; the top and bottom are moved 
toward the center by the amount specified by dv. If dh or dv is negative, the 
appropriate pair of sides is moved outward instead of inward. The effect is to 
alter the size by 2*dh horizontally and 2*dv vertically, with the rectangle 
remaining centered In the same place on tiie coordinate plane. 

If the resulting width or height becomes less than 1, the rectangle is set to 
the empty rectangle (0,0,0,0). 

Function SectRect (srcRectA^sroRectB: Rect; var dstRect: Rect) : 
boolean; 

SectRect calculates the rectangle that is the Intersection of the two input 
rectangles, and returns true if they indeed intersect or false if they do not. 
Rectangles that "touch" at a line or a point are not considered intersecting, 
because their intersection rectangle (really, in this case, an Intersection line 
or point) does not enclose any bits on the bitmap. 

If the rectangles do not intersect, the destination rectangle is set to (Oi)/),0). 
SectRect works correctly even if one of the source rectangles Is also the 
destination. 

Procedure UnionRect (srcRectA^srcRectB: Rect; var dstRect: Rect); 

UnionRect calculates the smallest rectangle which encloses both input 
rectangles. It works correctly even if one of the source rectangles Is also the 
destination. 
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Function PtInRect (pt: Point; r: Rect) : txnlean; 

PtinRect determines whether the pixel delow and to the right of the given 
coordinate point is enclosed in the specified rectangle, and returns tine if so 
or false If not. 

Procedure Pt2Rect (ptA^ptB: Point; var dstRect: Rect); 

Pt2Rect returns the smallest rectangle which encloses the two Input points. 

Procedure PtToAngle (r: Rect; pt: Point; var angle: integer); 

PtToAngle calculates an Integer angle between a line from the center of the 
rectangle to the given point and a line from the center of the rectangle 
pointing straight up (12 o'clock high). The angle Is In degrees from to 359, 
measured clockwise from 12 o'clock, with 90° at 3 o'clock, 180° at 6 o'clock, 
and 270° at 9 o'clock. Other angles are measured relative to the rectangle: If 
the line to the given point goes through the top right corner of the rectangle, 
the angle returned is 45 degrees, even If the rectangle Is not square; If It goes 
through the Dottom right corner, the angle Is 135 degrees, and so on (see 
Figure E-18). 



angle =45 



angle = 45 




Figure E-18 
PtToAngle 

The angle returned might be used as input to one of the procedures that 
manipulate arcs and wedges, as described In section E.9.10, Graphic operations 
on Arcs and Wedges. 

Function EqualRect (rectA,rectB: Rect) : boolean; 

EqualRect compares the two rectangles and returns true if they are equal or 
false if not. The two rectangles must have Identical boundary coordinates to 
be considered equal. 
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Function EnptyRect (r: Rect) : boolean; 

EmptyRect returns tiue if the given rectangle Is an empty rectangle or false 
If not. A rectangle is considered empty if the bottom coordinate is equal to 
or less than the top or the right coordinate is equal to or less than the left. 

E.9.7 Graphic dpeiations on Rectangles 

These procedures perform graphic operations on rectangles. See also 
ScrollRect in Section E.9.13^ Bit Transfer Operations. 

Procedure FrameRect (r: Rect); 

FrameRect draws an outline just inside the specified rectangle^ using the 
current grafPorfs pen pattern, mode, and size. The outline is as wide as the 
pen width and as tall as the pen height. It is drawn with the pnPat according 
to the pattern transfer mode specified by pnMode. The pen location is not 
changed by this procedure. 

If a region is open and being formed, the outside outline of the new rectangle 
is mathematically added to the region's boundary. 

Procedure PalntRect (r: Rect); 

PaintRect paints the specified rectangle with the current grafPort's pen 
pattern and mode. The rectangle on the bitmap is filled with the pnPat 
according to the pattern transfer mode specified Xi^)f pnModa The pen location 
is not changed by this procedure. 

Procedure EraseRect (r: Rect); 

EraseRect paints the specified rectangle with the current grafPort's back- 
ground pattern dkPat (in patCopy mode). The grafPort's pnPat and pnMode are 
ignored; the pen location is not changed. 

Procedure InvertRect (r: Rect); 

InvertRect inverts the pixels enclosed by the specified rectangle: every white 
pixel becomes black and every black pixel becomes white. The grafPort's 
pnPat, pnMode, and bkPat are all Ignored; the pen location is not changed. 

Procedure FlllRect (r: Rect; pat: Pattern); 

FillRect fills the specified rectangle with the given pattern (in patCopy mode). 
The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location is 
not changed. 
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E.9.8 Graphic operations on cvals 

Ovals are drawn inside rectangles tnat you specify. If the rectangle you 
specify is square^ QuickDraw draws a circle. 

Procedure FrameOval (r: Rect); 

Frameoval draws an outline just inside the oval that fits inside the specified 
rectangle, using the current grafPort's pen pattern, mode, and size. The 
outline is as wide as the pen width and as tall as the pen height It is drawn 
with the pnPat, according to the pattern transfer mode specified by pnMode. 
The pen location is not changed by this procedure. 

If a region is open and being formed, the outside outline of the new oval is 
mathematically added to the region's boundary. 

Procedure PalntOval (r: Rect); 

PaintOval paints an oval just Inside the specified rectangle with the current 
grafPort's pen pattern and mode. The oval on the bitmap is filled with the 
pnPat, according to the pattern transfer mode specified by pnMode. The pen 
location is not changed by this procedure. 

Procedure Eraseoval (r: Rect); 

EraseOval paints an oval just inside the specified rectangle with the current 
grafPort's background pattern bkPal (in j^tCopy mode). The grafPort's pnPat 
and pnMode are ignored; the pen location Is not changed. 

Procedure invertoval (r: Rect); 

InvertOval Inverts the pixels enclosed by an oval just inside the specified 
rectangle: every white pixel becomes black and every black pixel becomes 
white. The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen 
location is not changed. 

Procedure FlllOval (r: Rect; pat: Pattern); 

FillOval fills an oval just inside the specified rectangle with the given pattern 
(in patCopy mode). The grafPort's pnPat, pnMode, and dkPai are all ignored; 
the pen location is not changed. 

E.9.9 Graphic operations on Rounded-Comer Rectangles 

Procedure FraroeRoundRect (r: Rect; ovaliidth^ovalHelght: Integer); 

FrameRoundRect draws an outline just inside the specified rounded-corner 
rectangle, using the current grafPort's pen pattern, mode, and size. O/alWidth 
and ovalHeight specify the diameters of curvature for the comers (see Figure 
E-19). The outline is as wide as the pen width and as tall as the pen height. 
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It Is drawn with the pnPat, according to the pattern transfer mode specified 
by pnMode. The pen location is not changed by this procedure. 
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Figure E-19 
Rounded-Comer Rectangle 



If a region is open and being formed^ the outside outline of the new rounded- 
corner rectangle is mathematically added to the region's boundary. 

Procedure PalntRoundReet (r: Rect; ovalildth^ovaiHelgnt: Integer); 

PaintRoundRect paints the specified rounded-corner rectangle with the 
current grafPort's pen pattern and mode. OvalWldth and ovalHeight specify 
the diameters of curvature for the corners. The rounded-corner rectangle on 
the bitmap is filled with the pnPat according to the pattern transfer mode 
specified by pnMode. The pen location is not changed by this procedure. 

Procedure EraseRoundRect (r: Rect; ovaliidth, ovalHeight: integer); 

EraseRoundRect paints the specified rounded-corner rectangle with the 
current grafPort's background pattern bkPat (in patCopy mode). OvalWldth and 
ovalHeight specify the diameters of curvature for the corners. The grafPort's 
pnPat and pnMode are ignored; the pen location is not changed. 

Procedure invertRoundRect (r: Rect; ovaltfidth, ovalHeight: integer); 

InvertRoundRect inverts the pixels enclosed by the specified rounded-corner 
rectangle: every white pixel becomes black and every black pixel becomes 
white. OvalWldth and ovalHeight specify the diameters of curvature for the 
corners. The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen 
location is not changed. 
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Procedure FlllRoundRect (r: Rect; ovalildth,ovalHel^t: Integer; pat: 

Pattern); 

FlllRoundRect fills the specified rounded-corner rectangle with the given 
pattern (in patcopy mode). (XmlWidtn and ovalHelght specify the diameters of 
curvature for the comers. The grafPort's pnPal^ pnMode, and bkPat are all 
ignored; the pen location is not cnanged. 

E.9.10 Graphic Operations on Arcs and Wedges 

These procedures perform graphic operations on arcs and wedge-shaped 
sections of ovals. See also PtToAngle in Section E.9.6, Calculations with 
Rectangles. 

Procedure FrameArc (r: Rect; startAngle^arcAngle: Integer); 

FrameArc draws an arc of the oval that fits inside the specified rectangle, 
using the current grafPort's pen pattern, mode, and size. StartAngle indicates 
where the arc Degins and is treated mod 360. ArcAngle defines the extent of 
the arc. The angles are given in positive or negative degrees; a positive angle 
goes clockwise, while a negative angle goes counterclockwise. Zero degrees is 
at 12 o'clock high, 90" (or -270") is at 3 o'clock, ISO** (or -180") is at 6 
o'clock, and 270" (or -90°) is at 9 o'clock, other angles are measured relative 
to the enclosing rectangle: a line from the center of the rectangle through its 
top right corner is at 45 degrees, even if the rectangle Is not square; a line 
through the bottom right comer is at 135 degrees, and so on (see Figure E-20). 
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Figure E-20 
Operations on Arcs and Wedges 
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The arc Is as wide as the pen width and as tall as the pen height It Is drawn 
with the pnPat, according to the pattern transfer mode specified by pnMode. 
The pen location is not changed by this procedure. 

WARNItslG 

FrameArc differs from other QuickDraw procedures that frame shapes 
in that the arc is not mathematically added to the boundary of a 
region that is open and being formed. 



Procedure PaintArc (r: Rect; startAngle^arcAngle: integer); 

PaintArc paints a wedge of the oval just inside the specified rectangle with 
the current grafPorfs pen pattern and mode. startAngle and arcAngle define 
the arc of the wedge as In FrameArc. The wedge on the bitmap is filled with 
the pnPat according to the pattern transfer mode specified by pnModa The 
pen location is not changed by this procedure. 

Procedure EraseArc (r: Rect; startAngle, arcAngle: integer); 

EraseArc paints a wedge of the oval Just inside the specified rectangle with 
the current grafPorfs background pattern bkPat (in patcopy mode). 
StartAngle and arcAngle define the arc of the wedge as in FrameArc. The 
grafPorfs pnPat and pnMode are Ignored; the pen location is not changed. 

Procedure InvertArc (r: Rect; startAngle, arcAngle: integer); 

InvertArc inverts the pixels enclosed by a wedge of the oval Just Inside the 
specified rectangle: every white pixel becomes black and every black pixel 
becomes white. StartAngle and arcAngle define the arc of the wedge as in 
FrameArc. The grafPorfs pnPat, pnMode, and bkPat are all ignored; the pen 
location is not changed. 

Procedure FillArc (r: Rect; startAngle, arcAngle: integer; pat: 
Pattern); 

FillArc fills a wedge of the oval Just inside the specified rectangle with the 
given pattern (in patCopy mode). StartAngle and arcAngle define the arc of 
the wedge as in FrameArc. The grafPorfs pnPat, pnMode, and bkPat are all 
Ignored; the pen location is not changed. 
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E.9.11 calculations with Regions 

NEHE 

Remember that If the parameters to one of the calculation routines 
were defined in different grafPorts. you must first adjust them to be in 
the same coordinate system. If you do not adjust them> the result 
returned by the routine may be different from what you see on the 
screea To adjust to a common coordinate system^ see LocalToGiobal 
and GlobalToLocal in Section E.9.17^ Calculations with Points. 



Function NeiRgn : RgnHandie; 

NewRgn allocates space for a new, dynamic, variable-size region, initializes it 
to the empty region (0,0A0), and returns a handle to the new region, only 
this function creates new regions; all other procedures just alter the size and 
shape of regions you create. OpenPort calls NewRgn to allocate space for the 
port's vlsRgn and cUpRgn. 

WARNINGS 

Except when using visRgn or cUpRgru you must call NewRgn before 
specifying a region's handle in any drawing or calculation procedure. 

Never refer to a region without using its handle. 



Procedure DlsposeRgn (rgn: RgnHandie); 

DIsposeRgn deallocates space for the region whose handle is supplied, and 
returns the memory used by the region to the free memory pool, use this 
only after you are completely through with a temporary region. 

WARNING 

Never use a region once you have deallocated it, or you will risk being 
hung Xi)f dangling pointers! 



Procedure CopyRgn (srcRgn,dstRgn: RgnHandie); 

CopyRgn copies the mathematical structure of srcRgn into dstRgn; that is, it 
makes a duplicate copy of sicRgn. Once this is done, srcRgn may be altered 
(or even disposed of) without affecting dstRgn. CcpyRgn cfoes not create the 
cfestlnatJon region: you must use NewRgn to create the dstRgn before you 
call CopyRgn. 
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Procedure setEraptyRgn (rgn: RgnHandle); 

SetEmptyRgn destroys the previous structure of the given region, then sets the 
new structure to the empty region (0,0,0/J). 

Procedure SetRectRgn (rgn: RgnHandle; left^top^ri^t, bottom: integer); 

SetRectRgn destroys the previous structure of the given region, then sets the 
new structure to the rectangle specified by left, top, rlc^t, and bottom. 

If the specified rectangle is empty (i.e., left>-rlghl or top>-bottom), the region 
is set to the empty region (OjJiJi]). 

Procedure RectRgn (rgn: RgnHandle; r: Rect); 

RectRgn destroys the previous structure of the given region, then sets the new 
structure to the rectangle specified by r. This is operationally synonymous 
with SetRectRgn, except the input rectangle Is defined by a rectangle rather 
than by four boundary coordinates. 

Procedure OpenRgn; 

OpenRgn tells QuickDraw to allocate temporary space and start saving lines 
and framed shapes for later processing as a region definition. While a region 
is open, all calls to Line, LineTo, and the procedures that draw framed shapes 
(except arcs) affect the outline of the region. Only the line endpoints and 
shape boundaries affect the region definition; the pen mode, pattern, and size 
do not affect it. In fact, OpenRgn calls HIdePen, so no drawing occurs on the 
screen while the region is open (unless you called ShowPen just after OpenRgn, 
or you called ShowPen previously without balancing it by a call to HldePen). 
Since the pen hangs below and to the right of the pen location, drawing lines 
with even the smallest pen will change bits that lie outside the region you 
define. 

The outline of a region is mathematically defined and infinitely thin, and 
separates the bitmap into two groups of bits: those within the region and 
those outside it. A region should consist of one or more closed loops. Each 
framed shape itself constitutes a loop. Any lines drawn with Line or LineTo 
should connect with each other or with a framed shape. Even though the 
on-screen presentation of a region is clipped, the definition of a region is not; 
you can define a region anywhere on the coordinate plane with complete 
disregard for the location of various grafPort entities on that plane. 

When a region is open, the current grafPorfs rgnSave field contains a handle 
to information related to the region definition. If you want to temporarily 
disable the collection of lines and shapes, you can save the current value of 
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this field, set the field to niL and later restore the saved value to resume the 
region definition. 

WARNING 

Do not call OpenRgn while another region is already open. All open 
regions Put the most recent will behave strangely. 



Procedure CloseRgn (dstRgn: RgnHandle); 

closeRgn stops the collection of lines and framed shapes, organizes them into 
a region definition, and saves the resulting region into the region indicated h)} 
dstRgn. You should perform one and only one CloseRgn for every OpenRgn. 
CloseRgn calls ShowPen, balancing the HidePen call made by OpenRgn. 

Here's an example of how to create and open a region, define a barbell shape, 
close the region, and draw it: 

barbell := NewRgn; {make a new region} 

OpenRgn; {begin collecting stuff} 

SetRect(tefnpRect,20,20,30,50); {form the left weight} 

FrameOval(teiBpRect); 

SetRect(tenipRect,30,30,80,40); {form the bar} 

FraroeRect ( tempReot ); 

setRect(tempRect,80,20,90,50); {form the right weight} 

FraineOval( tempRect ); 

CloseRgn(barbell); {we're done; save in barbell} 

FillRgn(barbell, black); {draw it on the screen} 

DisposeRgn(barbell); {we don't need you anymora..} 

Procedure OffsetRgn (rgn: RgnHandle; dh,dv: integer); 

OffsetRgn moves the region on the coordinate plane, a distance of dh 
horizontally and dv vertically. This does not affect the screen unless you 
subsequently call a routine to draw the region. If dh and dv are positive, the 
movement is to the right and down; if either is negative, the corresponding 
movement Is in the opposite direction. The region retains its size and shape. 

NOTE 

OffsetRgn is an especially efficient operation, because most of the data 
defining a region is stored relative to ignBBox and so isn't actually 
changed by OffsetRgn. 
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Procedure InsetRgn (rgn: RgnHandle; dh^dv: Integer); 

insetRgn shrinks or expands tne region. All points on the region boundary are 
moved inwards a distance of dv vertically and dh horizontally; if dh or dv is 
negative, the points are moved outwards in that direction. InsetRgn leaves 
the region "centered" at the same position, but moves the outline in (for 
positive values of dh and dv) or out (for negative values of dh and dv). 
InsetRgn of a rectangular region works just like insetRect 

Procedure SectRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 

SectRgn calculates the intersection of two regions and places the intersection 
In a third region. Jhts does mt create tJw cfestJ/mUon n^on: you must use 
NewRgn to create dslRgn before you call SectRgn. The dslRgn can be one of 
the source regions, if desired. 

If the regions do not intersect, or one of the regions Is empty, the destination 
is set to the empty region (0,0,0,0). 

Procedure UhlonRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 

unionRgn calculates the union of two regions and places tne union in a tuird 
region. This does not create the destination region: you must use NewRgn to 
create dstRgn before you call unionRgn. The dstRgn can be one of the 
source regions. If desired. 

If both regions are empty, the destination Is set to the empty region (0,0/1,0). 

Procedure DiffRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 

DIffRgn subtracts srcRgnB from srcRgnA and places the difference In a third 
region. This does not create the destination region: you must use NewRgn to 
create dstRgn before you call DIffRgn. The dstRgn can be one of the source 
regions, if desired. 

If the first source region Is empty, the destination Is set to the empty region 
(0,0,0,0). 

Procedure XorRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 

xorRgn calculates the difference between the union and the Intersection of 
two regions and places the result in a third region. This does not create the 
destination region: you must use NewRgn to create dstRgn before you call 
XorRgn. The dstRgn can be one of the source regions. If desired. 

If the regions are coincident, the destination is set to the empty region 
(0,0,0,0). 
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Function PtInRgn (pt: Point; rgn: RgnHandle) : boolean; 

PtInRgn checks whether the pixel below and to the right of the given 
coordinate point is within the specified regioa and returns tine if so or false 
if not. 

Function RectlnRgn (r: Rect; rgn: RgnHandle) : dooleaa* 

RectlnRgn checks whether the given rectangle Intersects the specified region^ 
and returns true if the intersection encloses at least one bit or false if not. 

Function EqualRgn (rgnA,rgnB: rgnHandle) : boolean; 

EqualRgn compares the two regions and returns true if they are equal or false 
if not. The two regions must have identical sizes, shapes, and locations to be 
considered equal. Any two empty regions are always equal. 

Function EnptyRgn (rgn: RgnHandle) : tMolean; 

EmptyRgn returns true if the region is an empty region or false if not. Some 
of the circumstances in which an empty region can be created are: a NewRgn 
call; a CopyRgn of an empty region; a SetRectRgn or RectRgn with an empty 
rectangle as an argument; closeRgn without a previous OpenRgn or with no 
drawing after an OpenRgn; OffsetRgn of an empty region; InsetRgn with an 
empty region or too large an inset; SectRgn of nonintersectlng regions; 
UnionRgn of two empty regions; and DiffRgn or XorRgn of two identical or 
nonintersectlng regions. 

E.9.12 Graphic operations on Ftegions 

These routines all depend on the coordinate system of the current grafPort. If 
a region is drawn in a different grafPort than the one in which it was defined, 
it may not appear in the proper position inside the port. 

Procedure FraraeRgn (rgn: RgnHandle); 

FrameRgn draws a hollow outline Just inside the specified region, using the 
current grafPort's pen pattern, mode, and size. The outline is as wide as the 
pen width and as tall as the pen height; under no circumstances will the 
frame go outside the region boundary. The pen location Is not changed by 
this procedure. 

If a region Is open and being formed, the outside outline of the region being 
framed is mathematically added to that region's boundary. 

Procedure PalntRgn (rgn: RgnHandle); 

PaintRgn paints the specified region with the current grafPort's pen pattern 
and pen mode. The region on the bitmap Is filled with the pnPat, according 
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to the pattern transfer mode specified Xi)/ pnMode. The pen location is not 
changed by this procedure. 

Procedure EraseRgn (rgn: RgnHandle); 

EraseRgn paints the specified region with the current grafPort's background 
pattern bkPat (in patcopy mode). The grafPort's pnPat and pnMode are 
ignored; the pen location is not changed. 

Procedure InvertRgn (rgn: RgnHandle); 

InvertRgn inverts the pixels enclosed by the specified region: every white 
pixel becomes black and every black pixel becomes white. The grafPort's 
pnPat, pnMode, and bkPat are all ignored; the pen location is not changed. 

Procedure FlllRgn (rgn: RgnHandle; pat: Pattern); 

FillRgn fills the specified region with the given pattern (in patCopy mode). 
The grafPort's pnPat, pnMode, and dkPat are all ignored; the pen location is 
not changed. 

E.9.13 Bit Transfer qperations 

Procedure ScrollRect (r: Rect; dh,dv: Integer; updateRgn: RgnHandle); 

scrollRect shifts C'scroiis") those bits inside the intersection of the specified 
rectangle, vlsRgn, clipRgn, portRect, and portBlts-Dounds. The bits are shifted 
a distance of dh horizontally and dv vertically. The positive directions are to 
the right and down. No other bits are affected. Bits that are shifted out of 
the scroll area are lost; they are neither placed outside the area nor saved. 
The grafPort's background pattern bkPat fills the space created by the scroll. 
In addition, updateRgn is changed to the area filled with bkPat (see Figure 
E-21). 
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Bef oreScrollRect After Scro!lRect(dstRect,-1 0,5...) 




bkPat 



updateRgn 



Figure E-21 
Scrolling 



Figure E-21 shows mat the pen location after a scroiiRect Is In a different 
position relative to what was scrolled in the rectangle. The entire scrolled 
Item has been moved to different coordinates. To restore it to Its coordinates 
before the ScroiiRect, you can use the SetOrigin procedure. For example, 
suppose the dstRect here Is the portRect of the grafport and its top left 
corner is at (95,120). SetQrigin(105Al5) will offset the coordinate system to 
compensate for the scroll. Since the cUpRgn and pen location are not offset, 
they move down and to the left. 

Procedure CopyBits (srcBlts,dstBlts: BitMap; srcRect, dstRect: Rect; 
mode: Integer; maskRgn: RgnHandle); 

CopyBits transfers a bit Image between any two bitmaps and clips the result 
to the area specified by the maskRgn paranneter. The transfer may be 
performed In any of the eight source transfer modes. The result Is always 
clipped to the maskRgn and the boundary rectangle of the destination bitmap; 
If the destination bitmap Is tne current grafPort's portBlis, It Is also clipped 
to the Intersection of the grafPort's olipRgn and visRga If you do not want 
to Clip to a maskRgn, just pass nil for the maskRgn parameter. 

The dstRect and maskRgn coordinates are in terms of the dstBitsixxnds 
coordinate system, and the srcRect coordinates are in terms of the 
srcBitsJxjunds coordinates. 

The bits enclosed by the source rectangle are transferred into the destination 
rectangle according to the rules of the chosen mode. 
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The source transfer modes are as follows: 



srcCopy 
srcOr 



srcXor 
srcBlc 



notsrcCopy 
notSrcOr 



notSrcXor 
notSrcBic 



The source rectahgie is completely aligned with the destination rectangle; if 
the rectangles are of different sizes^ the bit image is expanded or shrunk as 
necessary to fit the destination rectangle. For example, if the bit image is a 
circle in a square source rectangle, and the destination rectangle is not 
square, the hit image appears as an oval in the destination (see Figure E-22). 



lllii 



Source Bitrnap 



Source 

Transfer 

Mode 






Destination Bitmap 




meskRgn 



Source Bitmap 



Destination Bitmap 



Figure E-22 
operation of copyBits 



E.9.14 Pictures 



Function qpenPlcture (plcFrame: Rect) : PlcHanaie; 

OpenPicture returns a handle to a new picture which has the given rectangle 
as its picture frame, and tells QuickDraw to start saving as the picture 
definition all calls to drawing routines and all picture comments (if any). 

OpenPicture calls HidePen, so no drawing occurs on the screen while the 
picture is open (unless you call ShowPen Just after OpenPicture, or you called 
ShowPen previously without balancing It by a call to HldePen). 

When a picture is open, the current grafPort's picSave field contains a handle 
to information related to the picture definition, if you want to temporarily 
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dlsaoie the collection of routine calls and picture comments, you can save the 
current value of this field, set the field to nil and later restore the saved 
value to resume the picture definition. 

WARNING 

Do not call OpenPlcture while another picture is already open. 



Procedure ciosePicture; 

ClosePlcture tells QuickDraw to stop saving routine calls and picture 
comments as the definition of the currently open picture. You should perform 
one and only one ClosePlcture for every OpenPlcture. CiosePicture calls 
ShowPen, balancing the HldePen call made by OpenPlcture. 

Procedure PlcCoinnent (klnd^dataSlze: Integer; dataHandle: QDHandle); 

PicComment inserts the specified comment into the definition of the currently 
open picture. Kind identifies the type of comment. DataHandle is a handle 
to additional data if desired, and datasize is the size of that data in bytes, if 
there is no additional data for the comment, dataHandle should be nil and 
datasize should be o. The application that processes the comment must 
Include a procedure to do the processing and store a pointer to the procedure 
in the data structure pointed to by the grafProcs field of the grafport (see 
Section E.10, Customizing QuickDraw Operations). 

Procedure DranPlcture (myPlcture: PlcHandle; dstRect: Rect); 

DrawPicture draws the given picture to scale in dstRect, expanding or 
Shrinking it as necessary to align the borders of the picture frame with 
dstRect DrawPicture passes any picture comments to the procedure accessed 
indirectly through the grafProcs field of the grafPort (see PicComment above). 

Procedure KillPicture (myPicture: PicHandle); 

KliiPicture deallocates space for the picture whose handle is suppllea and 
returns the memory used by the picture to the free memory pool. Use this 
only when you are completely through with a picture. 

E.9.15 Calculations with Polygons 

Function OpenPoly : PolyHandle; 

OpenPoly returns a handle to a new polygon and tells QuickDraw to start 
saving the polygon definition as specified by calls to line-drawing routines. 
While a polygon is open, all calls to Line and LlneTo affect the outline of the 
polygon. Only the line endpolnts affect the polygon definition; the pen mode, 
pattern, and size do not affect It. In fact, OpenPoly calls HldePen, so no 
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drawing occurs on the screen while the polygon is open (unless you call 
ShowPen just after OpenPoly^ or you called ShowPen previously without 
balancing it by a call to HldePen). 

A polygon should consist of a sequence of connected lines. Even though the 
on-screen presentation of a polygon is clipped^ the definition of a polygon is 
not; you can define a polygon anywhere on the coordinate plane with complete 
disregard for the location of various grafPort entities on that plane. 

When a polygon is open, the current grafPorfs polySave field contains a 
handle to information related to the polygon definition. If you want to 
temporarily disable the polygon definition you can save the current value of 
this field, set the field to nil, and later restore the saved value to resume the 
polygon definition. 

WARNIh4G 

Do not call OpenPoly while another polygon is already open. 



Procedure Closepoly; 

ClosePoly tells QuickDraw to stop saving the definition of the currently open 
polygon and computes the polyBBox rectangle. You should perform one and 
only one ClosePoly for every OpenPoly. ClosePoly calls ShowPen, balancing 
the HldePen call made by OpenPoly. 

Here's an example of how to open a polygon, define it as a triangle, close it, 
and draw it: 



triPoiy := OpenPoly/ 

MoveTo(300, 100); 

LlneTo(40a200); 

LlneTo(20Q,200); 

LlneTo(50a 100); 
ClosePoly; 

FlllPoly(trlPoly, gray); 
KlllPoly(triPoly); 



save handle and begin collecting stuff} 
move to first point and 
form 
the 
triangle 
stop collecting stuff 
draw It on the screen 
we're all done 



Procedure KillPoly (poly: PolyHandle); 

KillPoly deallocates space for the polygon whose handle is supplied, and 
returns the memory used Xi)i the polygon to the free memory pool, use this 
only after you are completely through with a polygon. 

Procedure OffsetPoly (poly: PolyHandle; dh,dv: integer); 

OffsetPoly moves the specified polygon on the coordinate plane, a distance of 
dh horizontally and dv vertically. This does not affect the screen unless you 



E-60 



Pascal Reference Manual 



QuickDraw 



suDsequentiy call a routine to draw tne polygon, if dh and dv are positive^ 
the movement is to the right and down; if either is negative^ the correspond- 
ing movement is in the opposite direction. The polygon retains its shape and 
size. 

NOTE 

OffsetPoly is an especially efficient operation^ because the data 
defining a polygon is stored relative to polyStart and so Isn't actually 
changed dy OffsetPoly. 



E.9.16 Graphic Operations on Polygons 

Procedure FramePoly (poly: PolyHandle); 

FramePoly plays back the line-drawing routine calls that define the given 
polygon, using the current grafPort's pen pattern, mode, and size. The pen 
will hang below and to the right of each point on the boundary of the 
polygon; thus, the polygon drawn will extend beyond the right and bottom 
edges of poly" "4»lyBBox by the pen width and pen height, respectively. All 
other graphic operations occur strictly within the boundary of the polygon, as 
for other shapes. You can see this difference in Figure E-23, where each of 
the polygons Is shown with Its polyBBox 





FramePoly 



PaintPoly 



Figure E-23 
Drawing Polygons 



If a polygon is open and being formed, FramePoly affects the outline of the 
polygon just as if the line-drawing routines themselves had been called. If a 
region is open and being formed, the outside outline of the polygon being 
framed is mathematically added to the region's boundary. 
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Procedure PalntPoly (poly: PolyHandle); 

PalntPoly paints the specified polygon with the current grafPort's pen pattern 
and pen mode. The polygon on the bitmap is filled with the pnPat^ according 
to the pattern transfer mode specified by pnModa The pen location Is not 
changed by this procedure. 

Procedure ErasePoly (poly: PolyHandle); 

ErasePoly paints the specified polygon with the current grafPort's background 
pattern bkPat (In patcopy mode). The pnPat and pnMode are Ignored; the pen 
location Is not changed. 

Procedure InvertPoly (poly: PolyHandle); 

invertPoly Inverts the pixels enclosed by the specified polygon: every white 
pixel becomes black and every black pixel becomes white. The grafPort's 
pnPat pnMode, and dkPat are all Ignored; the pen location Is not changed. 

Procedure FillPoly (poly: PolyHandle; pat: Pattern); 

FiilPoiy fills the specified polygon with the given pattern (in patcxipy mode). 
The grafPort's pnPat, pnMode, and bkPat are all Ignored; the pen location Is 
not changed. 

E.9.17 Calculations with Points 

Procedure AddPt (srcPt: Point; var dstPt: Point); 

AddPt adds the coordinates of srcPt to the coordinates of dstR, and returns 
the result in dslPt 

Procedure SUbPt (srcPt: Point; var dstPt: Point); 

SubPt subtracts the coordinates of srcPt from the coordinates of dstPt, and 
returns the result in dstPL 

Procedure SetPt (var pt: Point; h,v: integer); 

SetPt assigns two integer coordinates to a variable of type Point 

Function EqualPt (ptA^ptB: Point) : boolean; 

EqualPt compares the two points and returns true if they are equal or false If 
not 
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Procedure LocaiToGlobal (var pt: Point); 

LocalToGlobal converts the given point from the current grafPort's local 
coordinate system into a global coordinate system with the origin (0^3) at the 
top left comer of the port's bit image (such as the screen). This global point 
can then be compared to other global points, or be changed into the local 
coordinates of another grafPort 

Since a rectangle Is defined by two points, you can convert a rectangle into 
global coordinates by performing two LocalToGiobai calls, you can also 
convert a rectangle, region, or polygon into global coordinates by calling 
OffsetRect, OffsetRgn, or OffsetPoly. For examples, see GiobalToLocal below. 

Procedure GlodalToLocal (var pt: Point); 

GlobalToLocal takes a point expressed in global coordinates (with the top left 
comer of the bitmap as coordinate (0,0)) and converts it into the local 
coordinates of the current grafPort. The global point can be obtained with 
the LocalToGlobal call (see above). For example, suppose a game draws a 
"ball" within a rectangle named baliRect, defined In the grafPort named 
gamePort (as Illustrated below In Figure E-24). If you want to draw that ball 
In the grafPort named seiectPort, you can calculate the ball's selectPort 
coordinates like this: 

SetPort(gaiiiBPort); { start in origin port } 

selectBall := ballRect; { make a copy to be moved } 

LocalToGlot)al(selectBall.topLeft); { put both comers into } 

LocalToGlobal(select6all.botRight); { global coordinates } 

SetPort( selectPort); { switch to destination port} 

GlodalToLocal(selectBall.topLeft); { put both comers into } 
GlodalToLocal(selectBall.botRight);{ these local coordinates } 
FillOval(selectBall,ballCX)lor); { now you have the ball! } 
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Figure E-24 
Converting between Coordinate Systems 

You can see from Figure E-24 that LocalToGlobal and GlobalToLocal simply 
offset the coordinates of the rectangle by the coordinates of the top left 
corner of the local grafPort's boundary rectangle. You could also do this with 
OffsetRect. in fact^ the way to convert regions and polygons from one 
coordinate system to another is with OffsetRgn or OffsetPoly rather than 
LocalToGlobal and GlobalToLocal. For example^ if myRgn were a region 
enclosed by a rectangle having the same coordinates as ballRect in gamePort, 
you could convert the region to global coordinates with 

Off setRgn(myRgn, -20, -40); 

and then convert it to the coordinates of the selectPort grafPort with 
OffsetRgn(myRgn, 15, -30); 
E.9.18 Miscellaneous utilities 
Function Random : Integers- 
Random returns an integer, uniformly distributed pseudo-random, in the range 
from -32768 through 32767. The value returned depends on the global 
variable randSeed, which InitGraf initializes to l; you can start the sequence 
over again from where it began by resetting randSeed to i. 
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Function GetPixel (ruv: integer) : txwlean; 

GetPixel looks at the pixel associated with the given coordinate point and 
returns true if it is black or false if it is white. The selected pixel is 
immediately below and to the right of the point whose coordinates are given 
in h and v, in the local coordinates of the current grafPort. There is no 
guarantee that the specified pixel actually belongs to the port however; It 
may have been drawn by a port overlapping the current one. To see If the 
point Indeed belongs to the current port, call PtlnRgn(ptthePort".visRgn). 

Procedure stuff Hex (tningPtr: QDPtr; s: Str255); 

StuffHex pokes bits (expressed as a string of hexadecimal digits) Into any data 
structure. This is a good way to create cursors, patterns, or bit images to be 
"stamped" onto the screen with CopyBlts. For example. 

Stuff Hex(astrlpes, '0102040810204080') 

places a striped pattern into the pattern variable stripes. 
WARNING 

There Is no range checking on the size of the destination variable. It's 
easy to overrun the variable and destroy something if you don't know 
What you're doing. 



Procedure ScalePt (var pt: Point; srcRect,dstRect: Rect); 

A Width and height are passed In pt; the horizontal component of pt Is the 
width, and the vertical component of pt is the height. ScalePt scales these 
measurements as follows and returns the result In pt; It multiplies the given 
width by the ratio of dstRect's width to srcRect's width, and multiplies the 
given height by the ratio of dstRect's height to srcRect's height, in Figure 
E-25, where dstRect's width is twice srcRect's width and Its height Is three 
times srcRect's height, the pen width Is scaled from 3 to 6 and the pen height 
Is scaled from 2 to 6. 
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ScalePt scales pen size (3,2) to (6,6) 
MapPt maps point (3,2) to (18,7) 

Figure E-25 
ScalePt and MapPt 

Procedure ttapPt (var pt: Point; srcRect^dstRect: Rect); 

Given a point within srcRect MapPt maps it to a similarly located point 
within dstRect (that is^ to where it would fall if it were part of a drawing 
t)eing expanded or shrunk to fit dstRect). The result is returned in pt A 
corner point of srcRect would be mapped to the corresponding comer point of 
dstRect and the center of srcRecl to the center of dstRect In Figure E-25 
adove^ the point (3^) in srcRect is mapped to (18.7) in dstRect FromRect and 
dstRect may overlap, and pt need not actually be within srcRect 



E-66 



Pascal Reference Manual QuickDraw 
WARNING 

Remember, If you are going to draw inside the rectangle in dstRect 
you will probably also want to scale the pen size accordingly with 
ScalePt. 

Procedure HapRect (var r: Rect; srcRect^ dstRect: Rect); 

Given a rectangle within JicRect, MapRect maps it to a similarly located 
rectangle within dstRect by calling MapPt to map the top left and bottom 
right corners of the rectangle. The result is returned in r. 

Procedure ttapRgn (rgn: RgnHandle; srcRect^ dstRect: Rect); 

Given a region within srcRect, MapRgn maps it to a similarly located region 
within dstRect by calling MapPt to map all the points in the region. 

Procedure ttapPoly (poly: PolyHandle; srcRect^ dstRect: Rect); 

Given a polygon within srcRect MapPoly maps it to a similarly located 
polygon within dstRect by calling MapPt to map all the points that define the 
polygon. 

E.10 Customizing QuickDraw Operations 

For each shape that QuickDraw knows how to draw, there are procedures that 
perform these basic graphic operations on the shape: frame, paint, erase, 
invert, and fill. Those procedures in turn call a low-level drawing routine for 
the shape. For example, the FrameOval, PaintOval, EraseOval, InvertOval, and 
Fliiovai procedures all call a low-level routine that draws the oval. For each 
type of object QuickDraw can draw, including text and lines, there is a 
pointer to such a routine. By changing these pointers, you can Install your 
own routines, and either completely override the standard ones or call them 
after your routines have modified parameters as necessary. 

Other low-level routines that you can Install in this way are: 

• The procedure that does bit transfer and is called Xi)i CopyBits. 

• The function that measures the width of text and is called x^i Charv^idth, 
strlngwidth, and TextWidtn. 

• The procedure that processes picture comments and is called by 
DrawPicture. The standard such procedure Ignores picture comments. 

• The procedure that saves drawing commands as the definition of a picture, 
and the one that retrieves them. This enables the application to draw on 
remote devices, print to the disk, get picture input from the disk, and 
support large pictures. 



E-67 



Pascal Reference Manual 



QuickDraw 



The grafProcs field of a grafPort determines which low-level routines are 
called; if It contains nlL the standard routines are called, so that all 
operations in that grafPort are done in the standard ways descrioed in this 
appendix. You can set the grafProcs field to point to a record of pointers to 
routines. The data type of grafProcs is QDProcsPtn 



type QDProcsPtr = *QDProcs, 






QDProcs = record 






textProc: 


QDPtr; 


text drawing} 


llnePi'oc: 


QOPtr; 


line drawing} 


rectProc: 


QDPtr; 


(rectangle drawing} 


rRectProc: 


QOPtr; 


roundRect drawing} 


ovalProc: 


QDPtr; 


oval drawing} 


arcProc: 


QDPtr; 


{arc/wedge drawing} 


polyProc: 


QDPtr; 


polygon drawing} 


rgnProc: 


QOPtr; 


(region drawing} 


bitsProc: 


QOPtr; 


(bit transfer} 


coraroentProc: 


QDPtr; 


picture cornment 
processing} 


txMeasProc: 


QDPtr; 


text width measurement} 


getPlcProc: 


QDPtr; 


(Dictjjre retrieval} 


putPlcProc: 


QDPtr 


picture saving} 



end; 



Procedure SetStdProcs (var procs: QDProcs); 

SetStdProcs is provided to assist you in setting up a QDProcs record. It sets 
all the fields of the given QDProcs to point to the standard low-level 
routines. You can then change the ones you wish to point to your own 
routines. For example, if your procedure that processes picture comments is 
named MyComments, you will store SMyComments in the commentProc field 
of the QDProcs record. 

The routines you install must of course have the same calling sequences as 
the standard routines, which are described below. The standard drawing 
routines tell which graphic operation to perform from a parameter of type 
GrafVerb. 

type GrafVerb = (frame, paint, erase, invert, fill); 

When the grafVeib Is flli, the pattern to use when filling is passed in the 
flUPat field of the grafPort. 

Procedure StdText (byteCount: integer; textBuf : QDPtr; numer,denom: 
Point); 

StdText is the standard low-level routine for drawing text. It draws text from 
the arbitrary structure in memory specified by textBuf, starting from the first 
byte and continuing for byteCount bytes. Numer and denom specify the 
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scaling. If any: numer.v over ctenom.v gives the vertical scaling, and numer.h 
over denorah gives the horizontal scaling. 

Procedure StdLine (neuPt: Point); 

StdLine is the standard low-level routine for drawing a line. It draws a line 
from the current pen location to the location specified (in local coordinates) 
by newPt 

Procedure stdRect (verb: Graf Verb; r: Rect); 

StdRect is the standard low-level routine for drawing a rectangle. It draws 
the given rectangle according to the specified grafverb. 

Procedure StdRRect (verb: Graf Verb; r: Rect; ovalwidth^ovalHelght: 
Integer); 

StdRRect is the standard low-level routine for drawing a rounded-corner 
rectangle. It draws the given rounded-corner rectangle according to the 
specified grafverb. tX/alWldth and ovalHelght specify the diameters of 
curvature for the comers. 

Procedure StdOval (verb: Grafverb; r: Rect); 

stdOval is the standard low-level routine for drawing an oval. It draws an 
oval inside the given rectangle according to the specified grafverb. 

Procedure StdArc (verb: GrafVerb; r: Rect; startAngle,arcAngle: 
integer); 

StdArc Is the standard low-level routine for drawing an arc or a wedge. It 
draws an arc or wedge of the oval that fits inside the given rectangle. The 
grafVfert) specifies the graphic operation; if it's the frame operation, an arc is 
drawn; otherwise, a wedge is drawn. 

Procedure StdPoly (verb: GrafVerb; poly: PolyHandle); 

StdPoly Is the standard low-level routine for drawing a polygon, it draws the 
given polygon according to the specified grafVerb. 

Procedure StdRgn (verb: GrafVerb; rgn: RgnHandle); 

StdRgn is the standard low-level routine for drawing a region. It draws the 
given region according to the specified grafVerb. 
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Procedure StdBlts (var srcBlts: BltHap; var srcRect^dstRect: Rect; 
mode: integer; masKRgn: RgnHandle); 

SldBits is the standard low-level routine for doln^ bit transfer. It transfers a 
bit image between tne given bitmap and thePort 4»rtBlts^ just as if copyBits 
were called with the same paranneters and with a destination bitmap equal to 
thePort "4X3118115. 

Procedure StdOoniiient (kln0,dataslze: Integer; dataHandle: ODHandle); 

StdComment is the standard low-level routine for processing a picture 
comment. Kind Identifies the type of comment. DataHandle is a handle to 
additional data^ and dataSlze is the size of that data in bytes. If there is no 
additional data for the commands dataHandle will be nil and dataSize will be 
0, StdComment simply ignores the comment. 

Function stdTxfleas (bytecount: Integer; textBuf : QDPtr; var nuroer. 
denoro: Point; var info: Fontlnfo) : Integer; 

StdTxMeas is the standard low-level routine for measuring text width. It 
returns the width of the text stored in the arbitrary structure in memory 
specified by textBuf, starting with the first byte and continuing for bytecount 
bytes. Numer and denom specify the scaling as in the stdText procedure; note 
that StdTxMeas may change them. 

Procedure StdGetPic (dataPtr: QOPtr; bytecount: integer); 

StdGetPic is the standard low-level routine for retrieving information from 
the definition of a picture. It retrieves the next bytecount bytes from the 
definition of the currently open picture and stores them in the data structure 
pointed to by dataPtr. 

Procedure StdPutPlc (dataPtr: OOPtr; bytecount: integer); 

StdPutPic is the standard low-level routine for saving Information as the 
definition of a picture. It saves as the definition of the currently open 
picture the drawing commands stored in the data structure pointed to by 
dataPtr, starting with the first byte and continuing for the next bytecount 
bytes. 
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E.11 Using QuickDraw from Assembly Language 

All QuickDraw routines can be called from assennlDly-language programs as 
well as from Pascal. When you write an assembly-language program to use 
these routines, though, you must emulate Pascal's parameter passing and 
variable transfer protocols. 

This section discusses how to use the QuickDraw constants, global variables, 
data types, procedures, and functions from assembly language. 

The primary aid to assembly language programmers is a file named 
QD/GRAFTYPES.TEXT. If you use .INCLUDE to include this file when you 
assemble your program, all the QuickDraw constants, offsets to locations of 
global variables, and offsets into the fields of structured types will be 
available in symbolic form. 

E.11.1 Constants 

QuickDraw constants are stored in the QD/GRAFTYPES.TEXT file, and you 
can use the constant values symbolically. For example, if you've loaded the 
effective address of the thePort".txMocle field into address register A2, you 
can set that field to the srcxor mode with this statement: 

HOVE.i #SRCX0R,(A2) 

To refer to the number of bytes occupied by the QuickDraw global variables, 
you can use the constant GRAFSIZE. When you call the inltGraf procedure, 
you must pass a pointer to an area at least that large. 

E.11.2 Data Types 

Pascal's strong typing ability lets you write Pascal programs without really 
considering the size of a variable. But in assembly language, you must keep 
track of the size of every variable. The sizes of the standard Pascal data 
types are as follows: 



Type 


Size 


integer 


Word (2 bytes) 


iongint 


Long (4 bytes) 


boolean 


word (2 bytes) 


char 


Word (2 bytes) 


real 


Long (4 bytes) 



Integers and longlnts are in two's complement form; booleans have their 
boolean value in bit 8 of the word (the low-order bit of the byte at the same 
location); chars are stored in the high-order byte of the word; and reals are in 
the KCS standard format 
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The QuickDraw simple data types listed below are constructed out of these 
fundamental types. 



Type 


Size 


gunr 


Long (4 bytes) 


QDHandle 


Long (4 bytes) 


Word 


Long (4 bytes) 


Str255 


Page (256 bytes) 


Pattern 


8 bytes 


Bitsie 


32 bytes 



Other data types are constructed as records of variables of the above types. 
The size of such a type is the sum of the sizes of all the fields in the record; 
the fields appear in the variable with the first field in the lowest address. 
For example, consider the data type BitMap, which is defined as follows: 

type Bithap = record 

daseAddr: QOPtr; 
rowBytes: integer; 
bounds: Rect 
end; 

This data type would be arranged in memory as seven words: a long for the 
baseAddr, a word for the rowBytes, and four words for the top, left right, and 
bottom parts of the bounds rectangle. To assist you in referring to the fields 
inside a variable that has a structure like this, the QDA3R/^FTYPES.TEXT file 
defines constants that you can use as offsets into the fields of a structured 
variable. For example, to move a bitmap's rowBytes value into D3, you would 
execute the following instruction: 

mVE.W riY8ITriAP+R0IIBYTES,D3 

Displacements are given in the QD/GRAFTYPES.TEXT file for all fields of all 
data types defined by QuickDraw. 

To do double indirection, you perform an LEA indirectly to obtain the 
effective address from the handle. For example, to get at the top coordinate 
of a region's enclosing rectangle: 

MOVE.L riYHANDLE,Al ; Load handle into Al 

MOVE.L (A1),A1 ; Use handle to get pointer 

MOVE.* RGNBB0X+T0P(A1),D3 ; Load value using pointer 
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WARNING 

For regions (and all other variable-length structures with handles), you 
must not move the pointer into a register once and just continue to use 
that pointer; you must do the double indirection each time. Every 
QuickDraw call you make can possibly trigger a heap compaction that 
renders all pointers to movable heap items (like regions) invalid. The 
handles will remain valid, but pointers you've obtained through handles 
can be rendered Invalid at any subroutine call or trap in your program. 

E.11.3 Global Variables 

Register A5 always points to the section of memory where global variables 
are stored. The QD/GRAFTYPES.TEXT file defines a constant GRAFGLOB 
that points to the beginning of the QuickDraw variables in this space, and 
other constants that point to the individual variables. To access one of the 
variables, put GRAFGLOB in an address register, sum the constants, and index 
off of that register. For example, if you want to know the horizontal 
coordinate of the pen location for the current grafPort, which the global 
variable thePort points to, you can give the following instructions: 

MOVE.L GRAFGL0B(A5),A0 ; Point to QuickDraw globals 
MOVE.L THEP0RT(A0),A1 ; Get current grafPort 

hOVE.W PNL0C*H(A1),D0 ; Get thePort'.pnLoc.h 

E.11-4 Procedures and Functions 

To call a QuickDraw procedure or function, you must push all parameters to it 
on the stack, then JSR to the function or procedure. When you link your 
program with QuickDraw, these JSRs are adjusted to refer to QuickDraw's 
jump table, so that a JSR into the table redirects you to the actual location 
of the procedure or function. 

The only difficult part about calling QuickDraw procedures and functions is 
stacking the parameters. You must follow some strict rules: 

• Save all registers you wish to preserve before you begin pushing 
parameters. Any QuickDraw procedure or function can destroy the 
contents of the registers AO, Al, DO, Dl, and D2, but the others are never 
altered. 

• Push the parameters in the order that they appear in the Pascal procedural 
interface. 

• For booleans, push a byte; for integers and characters, push a word; for 
pointers, handles, long Integers, and reals, push a long. 

• For any structured variable longer than 4 bytes, push a pointer to the 
variable. 
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• For all var parameters, regardless of size, push a pointer to the variable. 

• When calling a function, first push a null entry equal to the size of the 
function result, timi push all other parameters. The result will be left on 
the stack after the function returns to you. 

Thls makes for a lengthy interface, but it also guarantees that you can mock 
up a Pascal version of your program, and later translate it into assembly code 
that works the same. For example, the Pascal statement 

blackness := GetPixel(50,inousePos.v); 

would be written in assembly language like this: 

; Save space for boolean result 

; Push constant 50 (decimal) 

; Push the value of raousePos.v 

; Call routine 

; Fetch result from stack 

This is a simple example, pushing and pulling word-long constants. Normally, 
you'll be pushing more pointers, using the PEA (Push Effective Address) 
instruction: 

FillRounORectCinyRect, l, thePort" .pnSize. v, i»hlte); 

PEA MYRECT ; Push pointer to myRect 

HOVE.i #1,-(SP) ; Push constait 1 

hOVE.L GRAFGL0B(A5),A0 ; Point to QuickDraw glodals 

MOVE.L THEP0RT<A0),A1 ; Get current grafPort 

riovE.i PNSIZE*V(A1),-(SP) ; Push value of thePort'.pnsize.v 

PEA IIHITE(AO) ; Push pointer to global variable white 

JSR FILLROUNDRECT ; Call the subroutine 

To call the TextFace procedure, push a word in which each of seven bits 
represents a stylistic variation: set bit for bold, bit 1 for italic, bit 2 for 
underline, bit 3 for ouUlne, bit 4 for shadow, bit 5 for condense, and bit 6 for 
extend. 



aR.i 


-(SP) 


MOVE.i 


#50, -(SP) 


hOVE.V 


MOUSEPOS+V, -(SP) 


JSR 


GETPIXEL 


HOVE.i 


(SP)+, BLACKNESS 
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E.12 Graf3D: Three-Dlrnenslonal Graphics 

Graf3D helps you map three-dimensional images onto the two-dimensional 
space used by QuickDraw. If this is your first exposure to three-dimensional 
graphics, you will find Graf3D's standard procedures and functions a great help 
in producing visually exciting graphs, charts, and drawings, if you are familiar 
with Applegraphics for the Apple II, you will feel right at home with Graf3D's 
use of real variables and world coordinates. 

With three-dimensional graphics you can present objects in true perspective, 
which will evoke for users their everyday environment Graf3D helps you 
represent complex business information pictorially; for example, a manager can 
see important relationships among sales, profits, and advertising dollars in a 
three-dimensional graph. 

You may be interested in a more theoretical discussion of three-dimensional 
graphics, including an explanation of some of the basic concepts of Graf3D, 
such as the viewing pyramid. A good, illustrated discussion appears in the 
section on three-dimensional computer graphics In Principles of interactive 
Computer Grapnics by William M, Newman and Robert F. Sproull (New York: 
McGraw-Hill, 1973). 

E.12.1 HOW Graf3D is Related to QuickDraw 

Graf3D Is a Pascal unit that makes the QuickDraw calls necessary to produce 
three-dimensional graphics. It provides you with an easy-to-use real number 
interface to QuickDraw's integer coordinates. You could, of course, write 
your own QuickDraw calls to perform the same functions Qraf3D provides for 
you, but that would be a little like going to the trouble of writing your own 
compiler. 

E.12.2 Features of Graf3D 

• A c&mra-eye view. This allows you to set the point of view from which 
the observer sees the object independently from the coordinates of the 
object Itself. The camera Is set up with the viewport, LookAt, and 
ViewAngle procedures. You can set the focal length of the camera as if 
you had a choice of telephoto, wide angle, or normal lenses. 

• mme-allmmslonal clipping tn a tjue pyramid. The apex of the pyramid is 
at the point of the camera eye, and the base of the pyramid is equivalent 
to the Viewport. When you use the Clip3D function, only objects forward 
of the camera eye and within the pyramid are displayed on the screen. 

• Two~aimenslonal point ana line capability using real coordinates. Graf 3D 
provides commands corresponding to the QuickDraw commands but using 
real coordinates instead of Integers, with real coordinates you have a 
larger dynamic range for graphics calculations; with Integer coordinates 
you get faster drawing time. For reals, the range is 

1.4 x 10"^^ to 3.a x IQ^^ 
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• Two-cflmemlonal or tJiree-cflm&yslonal rotation. You can rotate an object 
along any or all axes simultaneously, using tne Pitcn, Yaw, and Roll 
procedures. 

• Translation and scaling of objects In one or more axes simultaneously. 
Translation means movement anywhere in three-dimensional space. Scaling 
means shrinking or expanding. 

E.12.3 Graf3D Data Types 

Graf3D declares and uses the following data types: 

Point3D: A Polnt3D contains three real number coordinates: x, y, and z. 

Graf3D uses x, y, and z for real number coordinates to distinguish 
between the h and v integer screen coordinates in QuickDraw. 

Polnt2D: A Point2D is just like a PoInt3D but contains only x and y 
coordinates. 

XfMatrlx: The XfMatrix is a 4x4 matrix of real values, used to hold a 

transformation equation. Each transforming routine alters this 
matrix so that it contains the concatenated effects of all 
transformations applied. 

Port3DPtr: A Port3DPtr is a pointer to a Port3D. 

Port3D: A Port3D contains all the state variables needed to map real 

number coordinates into Integer screen coordinates. They are as 
follows: 

GPort: a pointer to the grafPort associated with this Port3D. 

viewRect: the viewing rectangle within the grafPort; the base of the 
viewing pyramid. 

xLeft, yTq3, xRight, yBottom: world coordinates corresponding to 
the viewRect 

pen: three-dimensional pen location. 

perPrirro: the pen location transformed by the xForm matrix. 

eye: three-dimensional viewpoint location established by ViewAngle. 

hSize, vsize: half-width and half-height of the viewRect in screen 
coordinates. 

WDenter, vCenter: center of the viewRect in screen coordinates. 

xCotan, yCotart viewing cotangents set up Xy^ ViewAngle, used by 
Clip3D. 

ident: a boolean that allows the transformation to be skipped when 
when xForm is an identity matrix. 

xForm: a 4x4 matrix that holds the net result of all transformations. 
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E.12.4 Graf3D Procedures and Functions 

The following procedures and functions are provided In Graf3D, 

Procedure 0pen3DPort(port: Port3DPtr); 

0pen3DPort initializes all tne fields of a Port3D to their defaults^ and makes 
tnat Port3D the current one. Gport is set to tne currently open grafPort. 
The defaults established are: 

tnePort30:=port; 

port* . GPort : =tnePort; 

Vie«Port( thePort \ portRect ); 

•ITH thePort*.portRect DO LookAt(left^tx>p, right, bottom); 

Vie«Angle(0); 

Identity; 

ri0VeT03D( 0,0,0); 

Procedure SetPort30(port: Port30Ptr); 

SetPort3D makes port the current Port3D and calls SetPort for that Port3D's 
associated grafPort. SetPort3D allows an application to use more than one 
Port3D and switch between them. 

Procedure GetPort3D(var port: Port3DPtr); 

GetPort3D returns a pointer to the current Port3D. This procedure is useful 
when you are using several Port3Ds and want to save and restore the current 
one. 

Procedure MoveTo2D()cy: real); Procedure rioveTo3D(x,y^z: real); 
Procedure riove20(d>cdy: real); Procedure riave3D(d)^dy,dz: real); 

These procedures move the pen in two or three dimensions without drawing 
lines. The real number coordinates are transformed by the xForm matrix and 
projected onto flat screen coordinates; then Graf3D calls QuickDraw's MoveTo 
procedure with the result. 

Procedure LlneTo20(>cy: real); Procedure LineTo5D(>cy^z: real); 
Procedure Llne2D(dx,dy: real); Procedure Llne30(dx,dy,dz: real); 

These procedures draw two- and three-dimensional lines from the current pen 
location. LlneTo2D and LineZD stay on the same z-plane. The real number 
coordinates are first transformed by the xForm matrix^ then clipped to the 
viewing pyramid, then projected onto the flat screen coordinates and drawn by 
calling QuickDraw's LineTo procedure. 
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Function clip3D(srcLsrcZ: Point3D; var clsti,dst2: Point): boolean; 

cllp3D Clips a three-dimensional line segment to the viewing pyramid and 
returns the clipped line projected onto screen coordinates. Clip3D returns 
tiue if any part of the line is visible. If no part of the line is within the 
viewing pyramid, Clip3D returns false. 

Procedure SetPt30(var pt3D: Polnt3D; x^y^z: real); 

setPt3D assigns three real numbers to a Polnt3D. 

Procedure setPt20(var pt20: Polnt20; x,y: real); 

SetPtZD assigns two real numbers to a Polnt2D. 

E.12A1 Setting Up the Camera (Viewport^ LookAt and vlewAngle) 

Procedures Viewport, LookAt and viewAngie position the image in the 
grafPort, aim the camera, and choose the lens focal length in order to map 
three-dimensional coordinates onto the flat screen space. These procedures 
may be called in any order. 

Procedure Viei(Port<r: Rect); 

Viewport specifies where to put the image in the grafPort. The Viewport 
rectangle is in integer QuickDraw coordinates, and tells where to map the 
LookAt coordinates. 

Procedure LookAt(left, top, right, bottom: real); 

LookAt specifies the real number x and y coordinates corresponding to the 
vlewRect 

Procedure vle«Angle(angle: real); 

ViewAngie controls the amount of perspective by specifying the horizontal 
angle (in degrees) subtended by the viewing pyramid. Typical viewing angles 
are 0** (no perspective), 10" (telephoto lens), 25" (normal perspective of the 
human eye), and 80" (wide angle lens). 

E.13.ft.2 The Transfoimatlon Matrix 

The transformation matrix allows you to impose a coordinate transformation 
between the coordinates you plot and the viewing coordinates. Each of the 
transformation procedures concatenates a cumulative transformation onto the 
>d=orm matrix. Subsequent lines drawn are first transformed by the xFoim 
matriX/ then projected onto the screen as specified by Viewport, LookAt, and 
ViewAngie. 

Procedure Identity; 

Identity resets the transformation matrix to an identity matrix. 
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Procedure Scale(xFactor,yFactor^zFactor: real); 

Scale modifies the transformation matrix so as to shrink or expand by >^aDtor, 
yFactor^ and zFactor. For example^ Scale(2.D;2.0^.0) will make everything 
come out twice as Olg when you draw. 

Procedure Translate(d5cdy^dz: real); 

Translate modifies the transformation matrix so as to displace by d>cdy/lz. 

Procedure Pitch(xAngle: real); 

Pitch modifies the transformation matrix so as to rotate xAngle degrees 
around the x axis. A positive angle rotates clockwise when looking at the 
origin from positive x 

Procedure Ya»(yAngle: real); 

Yaw modifies the transformation matrix so as to rotate yAngle degrees around 
the y axis. A positive angle rotates clockwise when looking at the origin 
from positive y. 

Procedure Roll(zAngle: real); 

Roll modifies the transformation matrix so as to rotate zAngle degrees around 
the z axis. A positive angle rotates clockwise when looking at the origin 
from positive z. 

Procedure Skew(zAngle: real); 

Skew modifies the transformation matrix so as to skew zAngle degrees 
around the z axis. Skew only changes the x coordinate; the result is much 
like the slant QuickDraw gives to Italic characters. (Skew(15.0) makes a 
reasonable Italic.) A positive angle rotates clockwise when looking at the 
origin from positive z. 

Procedure TransFonn(src: Polnt30; var dst: Polnt30); 

Transform applies the xForm matrix to src and returns the result as dst If 
the transformation matrix Is Identity^ dst will be the same as src. 
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E.15 QuickOiaw Interface 

UNIT QuickDraw; 

{ Copyright 1983 Apple cocnputer Inc. } 

INTERFACE 



CONST srccopy 


= 0; 


srcOr 


= 1; 


srcXor 


= 2; 


srcBic 


= 3; 


notSrcCopy 


= 4; 


notsrcor 


= 5; 


notSrcXor 


= 6; 


notSrcBlc 


= 7; 


patCopy 


= 8; 


patOr 


= 9; 


patxor 


= 10; 


patBic 


= 11; 


notPatCopy 


= 12; 


notPator 


= 13; 


notPatXor 


= 14; 


notPatBic 


= 15; 


{ QuickDraw color 


separat 


normalBit 


= 0; 


inverseBit 


= 1; 


redBit 


= 4; 


greenBit 


= 3; 


blueBit 


= 2; 


cyanBit 


= 8; 


n»yentaBlt 


= 7; 


yellowBit 


= 6; 


blackBit 


= 5; 


blackColor 


= 33; 


whiteColor 


= 30; 


redColor 


= 205; 


greenColor 


= 341; 


blueColor 


= 409; 


cyanColor 


= 273; 


magentaColor 


= 137; 


yellowColor 


= 69; 


picLParen 


= 0; 


picRParen 


= 1; 



{ the 16 transfer modes } 



{ normal screen mapping } 
{ Inverse screen mapping } 
{ RGB additive mapping } 



{ CMYBk suDtractive mapping } 



{ colors expressed in these meppings ) 



{ standard picture comments } 
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TYPE QOByte 


-128.. 127; 


QOPtr 


^QOByte; { blind pointer } 


ODHandle = 


"ODPtr; { blind handle } 


Str255 


Strlng[255]; 


Pattern = 


PACKED ARRAY[0..7] OF 0..255; 


Bltsie 


ARRAY [0.. 15] OF INTEGER; 


VHSelect = 


(V,h); 


GrafVerb = 


(frame, paint, erase, invert, fill); 


styleltem = 


(bold, Italic, underline, outline, shadow, condense. 




extend); 


Style 


SET OF Styleltenu 


Fontlnfo = 


RECORD 




ascent: INTEGER; 




descent: INTEGER; 




wldttax: INTEGER; 




leading: INTEGER; 




END; 


Point = RECORD CASE INTEGER OF 


0: 


(v: INTEGER; 


h: 


INTEGER); 



1: (Vh: ARRAY [VHSelect] OF INTEGER); 
END; 

Rect = RECORD CASE INTEGER OF 



0: (top: 
left: 
bottom: 
right: 



INTEGER; 
INTEGER; 
INTEGER; 
INTEGER); 



1: (topLeft: Point; 
botRight: Point); 
END; 



E-81 



Pascal Reference Manual QuickDraw 



\ Bltnap = RECORD 

baseAddr: QOPtr; - 
rowBytes: INTEGER; 

/ bounds: Rect; 

/ ENQ; 



Cursor = RECORD 

data: Bitsl6; 
mask: Bltsl6; 
hotSpot: Point; 
END; 



Penstate = RECORD 

pnLoc: Point; 

pnSlze: Point; 

pnMode: INTEGER; 

pnPat: Pattern; 
END; 



PolyHandle = "PolyPtr; 
PolyPtr = "Polygon; 
Polygon = RECORD 

polySize: INTEGER; 
polyBBox: Rect; 
polyPoints: ARRAY [0..0] OF Point; 
END; 



RgnHandle = "RgnPtr; 
RgnPtr = "Region; 
Region = RECORD 

rgnSize: INTEGER; { rgnSize = 10 for rectangular } 

rgnBBox: Rect; 

{ plus more data if not rectangular } 

END; 



PlcHandle = TicPtr; 



PicPtr 


= "Picture; 


Picture 


= RECORD 




picSize: INTEGER; 




picFrafne: Rect; 




{ plus byte codes for picture content } 




END; 
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ODProcsPtr = "QDProcs; 




ODProcs - RECORD 




textProc: 


QOPtr; 


lineProc: 


qOPtr; 


rectProc: 


ODPtr; 


rRectProc: 


QOPtr; 


ovalProc: 


QOPtr; 


arcProc: 


QDPtr; 


polyProc: 


QOPtr; 


rgnProc: 


QOPtr; 


bitsProc: 


QOPtr; 


comroentProc: 


QOPtr; 


txMeasProc: 


QOPtr; 


getPicProc: 


QOPtr; 


putPicProc: 


QDPtr; 


END; 




GrafPtr = "GrafPort; 




GrafPort = RECORD 




device: 


INTEGER; 


portBits: 


BitMap; 


portRect: 


Rect; 


visRgn: 


RgnHandle; 


clipRgn: 


RgnHandle; 


dkPat: 


Pattern; 


flllPat: 


Pattern; 


pnLoc: 


Point; 


pnSize: 


Point; 


pnMode: 


INTEGER; 


pnPat: 


Pattern; 


pnVls: 


INTEGER; 


txFont; 


INTEGER; 


txFace: 


Style; 


txMode: 


INTEGER; 


txsize: 


INTEGER; 


spExtra: 


Longint; 


fgColor: 


Longint; 


bkColor: 


Longint; 


colrBit: 


INTEGER; 


patstretch: 


INTEGER; 


plcSave: 


QDHandle; 


rgnSave: 


QDHandle; 
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polySave: 


ODHandle; 




grafProcs: 


QDProcsPtr; 




END; 




VAR thePort: 


GrafPtr; 




white: 


Pattern; 




black: 


Pattern; 




gray: 


Pattern; 




ItGray: 


Pattern; 




dkGray: 


Pattern- 




arrow: 


Cursor; 




screenBlts: 


BitMap; 




randSeed: 


Longint; 





{ GrafPort Routines } 

PROCEDURE InitGraf (globalPtr: QDPtr); 

PROCEDURE OpenPort (port: GrafPtr); 

PROCEDURE initPort (port: GrafPtr); 

PROCEDURE ClosePort (port: GrafPtr); 

PROCEDURE SetPort (port: GrafPtr); 

PROCEDURE GetPort (VAR port: GrafPtr); 

PROCEDURE Graf Device (device: INTEGER); 

PROCEDURE SetPortBits(Dni: BitMap); 

PROCEDURE PortSize (width, height: INTEGER); 

PROCEDURE MovePortTo (leftGlobaLtopGlobal: INTEGER); 

PROCEDURE SetOrigin (h,V: INTEGER); 

PROCEDURE setciip (rgn: RgnHandle); 

PROCEDURE GetClip (rgn: RgnHandle); 

PROCEDURE ClipRect (r: Rect); 

PROCEDURE BackPat (pat: Pattern); 



{ Cursor Routines } 

PROCEDURE inltCursor; 
PROCEDURE SetCursor(crsr: Cursor); 
PROCEDURE HldeCursor; 
PROCEDURE ShowCursor; 
PROCEDURE ObscureCursor; 
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{ Line Routines } 

PROCEDURE HidePen; 
PROCEDURE ShOWPen; 

PROCEDURE GetPen (VAR pt: Point); 
PROCEDURE GetPenState(VAR pnState: PenState); 
PROCEDURE SetPenState(pnState: PenState); 

PROCEDURE PenSize (width, height: INTEGER); 

PROCEDURE Pennode (mode: INTEGER); 

PROCEDURE PenPat (pat: Pattern); 
PROCEDURE PenNonual; 

PROCEDURE HoveTO (h,v: INTEGER); 

PROCEDURE Move (dh.dv: INTEGER); 

PROCEDURE LineTO (h,V: INTEGER); 

PROCEDURE Line (dh,dv: INTEGER); 



{ Text Routines } 



PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

FUNCTION 

FUNCTION 

FUNCTION 



TextFont 

TextFace 

TextMode 

TextSize 

SpaceExtra 

DrawChar 

Drawstring 

DrawText 

Chariidth 

Stringwidth 

TextWidth 



PROCEDURE GetFontlnfo 



(font: INTEGER); 

(face: Style); 

(mode: INTEGER); 

(size: INTEGER); 

(extra: Longint); 

(ch: char); 

(s: Str255); 

(textBuf: QDPtr; firstByte.byteCount: INTEGER); 

(ch: CHAR): INTEGER; 

(S: Str255): INTEGER; 

(textBuf: QDPtr; f irstByte^ byteCouht : INTEGER): 

INTEGER; 
(VAR info: Fontlnfo); 



{ Point Calculations ) 



PROCEDURE 


AddPt 


PROCEDURE SubPt 


PROCEDURE SetPt 


FUNCTION 


EqualPt 


PROCEDURE 


ScalePt 


PROCEDURE 


ttapPt 


PROCEDURE LocalToGlobal 


PROCEDURE 


GlobalToLocal 



(src: Point; UAR dst: Point); 
(src: Point; VAR dst: Point); 
(VAR pt: Point; h,V: INTEGER); 
(ptl,pt2: Point): BOOLEAN; 
(VAR pt: Point; 
(VAR pt: Point; 
(VAR pt: Point); 
(VAR pt: Point); 



fromRect^toRect: Rect); 
fromRect,toRect: Rect); 
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{ Rectangle Calculations } 



PROCEDURE SetRect 
FUNCTION EqualRect 
FUNCTION EliptyRect 
PROCEDURE OffsetRect 

PROCEDURE riapRect 
PROCEDURE InsetRect 
FUNCTION SectRect 
PROCEDURE unlonRect 
FUNCTION PtInRect 
PROCEDURE Pt2Rect 



(VAR r: Rect; left top, right, bottom: INTEGER); 

(recti, rect2: Rect): BOOLEAN; 

(r: Rect): BOaEAN; 

(VAR r: Rect; dh,ClV: INTEGER); 

(VAR r: Rect; fromRect,toRect: Rect); 

(VAR r: Rect; dh,ClV: INTEGER); 

(srcl,src2: Rect; VAR dstRect: Rect): BOOLEAN; 

(srcl,src2: Rect; VAR dstRect: Rect); 

(pt: Point; r: Rect): BOOLEAN; 

(ptl,pt2: Point; VAR dstRect: Rect); 



{ Graphical Operations on Rectangles } 

PROCEDURE FraroeRect (r: Rect); 
PROCEDURE PalntRect (r: Rect); 
PROCEDURE EraseRect (r: Rect); 
PROCEDURE InvertRect (r: Rect); 
PROCEDURE FillRect (r: Rect; pat: Pattern); 



{ RotncffJect Routines } 

PROCEDURE FraroeRoundRect (r: Rect; ov«d,ovHt: 

PROCEDURE PalntRoundRect (r: Rect; ovUd^ovHt: 

PROCEDURE EraseRoundRect (r: Rect; ovWd,ovHt: 

PROCEDURE InvertRoundRect (r: Rect; ovWd,ovHt: 

PROCEDURE FlllRoundRect (r: Rect; ovWd,ovHt: 



INTEGER); 
INTEGER); 
INTEGER); 
INTEGER); 
INTEGER; pat: Pattern); 



{ Oval Routines } 

PROCEDURE Fraroeoval (r: Rect); 
PROCEDURE PaintOval (r: Rect); 
PROCEDURE EraseOval (r: Rect); 
PROCEDURE InvertOval (r: Rect); 
PROCEDURE Fliioval (r: Rect; pat: Pattern); 



{ Arc Routines } 

PROCEDURE FrameArc (r: Rect; 

PROCEDURE PalntArc (r: Rect; 

PROCEDURE EraseArc (r: Rect; 

PROCEDURE invertArc (r: Rect; 



startAngle,arcAngle: INTEGER); 

startAngle,arcAngle: INTEGER); 

8tartAngle,arcAngle: INTEGER); 

startAngle,arcAngle: INTEGER); 
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PROCEDURE FlllArc (r: Rect; startAngle^arcAngle: INTEGER; pat: 

Pattsrn \ * 
PROCEDURE PtToAngle (r: Rect; pt: Point; VAR angle: INTEGER); 



{ Polygon Routines } 



FUNCTION 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 



OpenPoly: 

ClosePoly; 

KillPoly 

OffsetPoly 

MapPoly 

FramePoly 

PaintPoly 

ErasePoly 

invertPoly 

FillPoly 



PolyHandle; 

(poly: PolyHandle); 

(poly: PolyHandle; dh^dv: INTEGER); 

(poly: PolyHandle; froraRect^toRect: Rect); 

(poly: PolyHandle); 

(poly: PolyHandle); 

(poly: PolyHandle); 

(poly: PolyHandle); 

(poly: PolyHandle; pat: Pattern); 



{ Region Calculations } 



FUNCTION 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

FUNCTION 

FUNCTION 

FUNCTION 

FUNCTION 



NewRgn: RgnHandle; 

DisposeRgn(rgn: RgnHandle); 

CopyRgn (srcRgn^dstRgn: RgnHandle); 

SetEn|)tyRgn(rgn: RgnHandle); 

SetRectRgn(rgn: RgnHandle; left, top^ right, Ijottom: INTEGER); 



(rgn: RgnHandle; r: Rect); 
(dstRgn: RgnHandle); 



RectRgn 

OpenRgn; 

CloseRgn 

Offset^ (rgn: RgnHandle; dh,dv: INTEGER); 



MapRgn (rgn: RgnHandle; fromRect^toRect: 

InsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 

SectRgn (srcRgnA^srcRgnB, dstRgn: RgnHandle); 

UnionRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 

DiffRgn (srcRgnA/SrcRgnB, dstRgn: RgnHandle); 

xorRgn (srcRgnA^srcRgnB, dstRgn: RgnHandle); 

EqualRgn (rgnA^rgnB: Rgn^tendle): BOOLEAN; 

EnptyRgn (rgn: RgnHandle): BOOLEAN; 

PtInRgn (pt: Point; rgn: RgnHandle): BOOLEAN; 

RectlnRgn (r: Rect; rgn: RgnHandle): BOOLEAN; 



Rect); 



{ Graphical Operations on Regions } 



PROCEDURE FrameRgn 
PROCEDURE PaintRgn 
PROCEDURE EraseRgn 



(rgn: RgnHandle); 
(rgn: RgnHandle); 
(rgn: RgnHandle); 
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PROCEDURE InvertRgn (rgn: RgnHandle); 

PROCEDURE FlllRgn (rgn: RgnHandle; pat: Pattern); 



{ Grapnical Operations on BitMaps } 

PROCEDURE ScrollRectCdstRect: Rect; dh^dv: INTEGER; updateRgn: 

rgnHandle); 
PROCEDURE CopyBits (srcBits^dstBits: BitMap; 

srcRect^dstRect: Rect; 

mode: INTEGER; 

maskRgn : RgnHandle ); 

{ Picture Routines } 

FUNCTION OpenPicture(picFrame: Rect): PicHandle; 

PROCEDURE ClosePlcture; 

PROCEDURE DrawPicture(myPicture: PicHandle; dstRect: Rect); 

PROCEDURE PicConiment(kind.dataSize: INTEGER; dataHandle: QDHandle); 

PROCEDURE KlllPicture(myPicture: PicHandle); 



{ The Bottleneck interface: } 



PROCEDURE 
PROCEDURE 

PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 

PROCEDURE 
PROCEDURE 
PROCEDURE 

PROCEDURE 
FUNCTION 



PROCEDURE 
PROCEDURE 



SetStdProcs(VAR procs: QDProcs); 

StdText (count: INTEGER; textAddr: QDPtr; numer^denom: 

Point); 
StdLine (newPt: Point); 
StdRect (verb: Graf Verb; r: Rect); 
StdRRect (verb: Graf Verb; r: Rect; ovIld^ovHt: INTEGER); 
StdOval (verb: Graf Verb; r: Rect); 
StdArc (verb: Graf Verb; r: Rect; startAngle^arcAngle: 

INTEGER); 
StdPoly (verb: Graf Verb; poly: PolyHandle); 
StdRgn (verb: Graf Verb; rgn: RgnHandle); 
StdBits (VAR srcBits: BitMap; VAR srcRect^dstRect: Rect; 

fnode: INTEGER; maskRgn: RgnHandle); 
StdComment (kind^dataSize: INTEGER; dataHandle: QDHandle); 
StdTxMeas (count: INTEGER; textAddr: ODPtr; 

VAR numer^denom: Point; 

VAR info: FontlnfO): INTEGER; 
StdGetPic (dataPtr: QDPtr; byteCount: INTEGER); 
StdPutPlc (dataPtr: QDPtr; byteCount: INTEGER); 
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{ Misc Utility Routines } 

FUNCTION GetPixel (h.v: INTEGER): BOOLEAN; 
FUNCTION Random: INTEGERS- 
PROCEDURE Stuff Hex (thlngptr: ODPtr; s:Str255); 
PROCEDl^ ForeColor (color: Longint); 
PROCEDURE BackColor (color: Longint); 
PROCEDURE ColorBit (whlchBit: INTEGER); 

E.13.1 Giaf3D Interface 

{$s Graf } 

UNIT Graf3D; 

{ three-dimensional graphics routines layered on top of QuickDraw } 

INTERFACE 

USES {$U QO/QuickDra».OBJ } QuickDraw; 

CONST radConst =57. 29578; 

TYPE Point3D=REC0RO 

x: REAL; 
y: REAL; 
z: REAL; 
END; 

Point2D»REC0RD 

x: REAL; 
y: REAL; 
END; 

Xf Matrix = ARRAY [ . . 3. . . 3 ] OF REAL; 
PortJOPtr - "Port30; 
Port3D = RECORD 

GPort: GrafPtr; 

viewRect: Rect; 

xLef t^ yTop, xRight, yBottom : REAL; 

pea penPrime^ eye : Point3D; 

hSize^vSize: REAL; 

hCenter, vCenter : REAL; 

xCotan^yCotan: REAL; 

ident: BOOLEAN; 

XForm: Xf Matrix; 
END; 
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VAR tnePort3D; PortJOPtr; 



PROCEDURE 0pen30Port 
PROCEDURE SetPort3D 
PROCEDURE GetPort3D 



(port: Port5DPtr); 
(port: Port3DPtr); 
(VAR port: Port3DPtr); 



PROCEDURE riOVeTo20(x,y: REAL); 

PROCEDURE LineT02D(>cy: REAL); 

PROCEDURE Move2D(elX,Cly: REAL); 

PROCEDURE Llne2D(d)0Cly: REAL); 



PROCEDURE M0VeT05D(x,y^Z: REAL); 
PROCEDURE LlneT05D(x,y.2: REAL); 
PROCEDURE Move30(d)CCly.Cl2: REAL); 
PROCEDURE Line3D(dx.Cly,dz: REAL); 



PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
FUNCTION 



Viewport 

LookAt 

VlewAngle 

Identity; 

Scale 

Translate 

Pitcrv 

Yaw 

Roll 

Skew 

TransForm 

ciip3D 



PROCEDURE SetPt3D 
PROCEDURE SetPt2D 



(r: Rect); 

( lef t^ top, right, bottom : REAL ); 

(angle: REAL); 

(xFactor, yFactor, zFactor : REAL ); 

(dx^dy^dZ] REAL); 

(xAngle: KtAL); 

(yAngle: REAL); 

(zAngle: REAL); 

(zAngle: REAL); 

(src: Point30; VAR dst: Point3D); 

(srcl,src2: P0int3D; VAR dStl,dSt2: POINT); 



(VAR pt3D: Point3D; X,y,Z: REAL); 
(VAR pt20: PolntZD; )^y: REAL); 
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E.14 QuiciOraw Sample Programs 

This section provides listings of two sample programs that are Included with 
the Workshop software. 

E.14.1 QDSample 

The program QDSample (In the file G}DA3DSample.TEXT) demonstrates 
different things that QuickDraw can da Its output Is shown In Figure E-26. 



Look M'hat you can droMK M^ith QuickDroM' 



Text 

Bold 

Italic 
Underline 




Rectangles 




RoundRects 




Bit Images 



fg ...P 



mmm 



k'edges 




Polygons 




Regions 

Arbitrary Clippij5ii-^]e;giol 
Irbitrajp^* Clitt'^ ^or 
Irbltr/ Nllijf br 

Irbif \iik Jm 
^rb" \pmr-«T'egior 

Cr ummy LiipiD ing Regior 



Glials 




Figure E-26 
QDSample 

The file QD/MA3DSample.TEXT is an exec file that can be used to rebuild 
this sample program. Disregard any warning messages from the linker about 
name conflicts. 
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PROGRAM gosanpie; 

{ Sample program illlustratlng the use of QuickDraw. } 

USES {$U QD/QuickDraw.08J } quickDraw, 

{$U QO/ODSupport.OBJ } QOSupport; 

TYPE ICOnOata = ARRAY [0.. 95] OF INTEGER; 

VAR heapBuf: ARRAY[0.. 10000] OF INTEGER; 
myPort: Graf Port; 
icons: ARRAY [0.. 5] OF iconData; 



FUNCTION HeapFull(hz: QDPtr; bytesNeeded: INTEGER): INTEGER; 

{ this function will be called If the heapzone runs out of space } 

BEGIN 

WRITELNCThe heap Is full. The program must now terminate! '); 

Halt; 
END; 



PROCEDURE Inltlcons; 

{ Hanually stuff some Icons. Normally we would read them from a file } 

BEGIN 



{ Lisa } 

StuffHex(alcons[0^ 0], 
StuffHex(alcons[0, 12], 
Stuf f Hex(aicons[ 0, 24], 
StuffHex(alcons[0, 36], 
Stuff Hex(alcons[0, 48], 
Stuf f Hex(aicons[ 0, 60 ], 
StuffHex(alcons[0, 72], 
Stuf fHex(aicons[0, 84], 



' OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOIFFFFFFFFC ' ); 
' 00600000000601800000000B0600000000130FFFFFFFFFA3* ); 
' 18000000004311FFFFF00023120000080F231200000BF923' ); 
' 120000080F23120000080023120000080023120000080F23' ); 
• 1200000BF923120000080F2312000008002311FFFFF00023' ); 
' 08000000004307FFFFFFFFA30100000000260FFFFFFFFE2C ' ); 
• 18000000013832AAAAA8A9F0655555515380C2AAAA82A580' ); 
• 800000000980FFFFFFFFF300800000001600FFFFFFFFFCOO ' ); 



{ Printer } 

StuffHex(alcons 

StuffHex(aicons 

StuffHex(aicons 

stuffHex(aicons 

StuffHex(alcons 

StuffHex(alcons 

StuffHex(alcons 

StuffHex(aicons 



1. 

1,12 

1,24 

1,36 

1,48 

1,60" 

1,72 

1,84 



• 000000000000000000000000000000000000000000000000* ); 
• 00000000000000007FFFFF00000080000280000111514440' ); 
• 0002000008400004454510400004000017C00004A5151000 " ); 
• 0004000010000004A54510000004000017FEOOF4A5151003' ); 
• 0184000013870327FFFFF10F06400000021B0CFFFFFFFC37 * ); 
• 18000000006B3000000000D77FFFFFFFFFABC00000000356' ); 
• 8000000001AC87F000000158841000CCC1B087FOOOCCC160 ' ); 
• 8000000001COC000000003807FFFFFFFFF0007800001EOOO' ); 
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{ Trash Can } 
StuffHex(aicons[2. 
Stuf fHex(aicons[2. 12 
StuffHex(aicons[2.24 
Stuff Hex(aicons[2. 36 
StuffHex(aicons[2,48 
StuffHex(aicons[2,60 
Stuf fHex(aicons[2^ 72 
StuffHex(aicons[2.84 

{ tray } 

StuffHex(aicons[5^ 

StuffHex(aicons[3. 12 

StuffHex(aicons[3.24 

StuffHex(aicons[3.36 

StuffHex(aicons[3,48 

StuffHex(aicons[3,60 

StuffHex(aicons[3.72 

StuffHex(aicons[3.84 

{ File CaDinet } 
StuffHex(alcons[4^ 
Stuff Hex(aicons[4, 12 
stuff Hex(aicons[4, 24 
Stuff Hex(aicons[4. 36 
StuffHex(alcons[4,48 
Stuff Hex(aicons[4. 60 
Stuf fHex(aicx)ns[4, 72 
Stuff Hex(aicons[4^ 84 

{ drawer } 

StuffHex(aicons[5^ 
Stuff Hex(aicx)ns[5. 12 
Stuff Hex(aicons[5, 24 
Stuff Hex(aicons[5. 36 
Stuff Hex(aitx>ns[5, 48 
Stuf fHex(aicons[5. 60 
Stuff Hex(aicons[5. 72 
StuffHex(aicons[5.84 

END; 



, •000001FCOOOOOOOOOE0600000000300300000000C0918000" ); 
. "000138498000000260498000000400930000000861260000 • ); 
, '0010064FE0000031199830000020E6301800002418E00800' ); 
. ■0033E3801C000O180E0O2CO000OFF801CCO0OO047FFE0C00' ); 
, •000500004C000005259A4C000005250A4C00000525FA4COO' ); 
, •000524024C00000524924C00600524924C0090E524924C7C' ); 
, •932524924C82A44524924001C88524924CF1004524924C09' ); 
. '0784249258E70003049233100000EOOOE40800001FFFC3FO' ); 



, '000000000000000000000000000000000000000000000000' ); 
. '0000000000000000000000000000000000000007FFFFFFFO' ); 
, •OOOE00000018001A00000038003600000078006AOOOOOOD8' ); 
. •O0D7FFFFFFB801ACO000035803580O00O6B807FCO00FFD58' ); 
, '040600180AB80403FFFOOD58040000000AB8040000000D58' ); 
. •040000000AB807FFFFFFFD5806ACOOOOOAB8055800000D58' ); 
, •06B0OOO00AB807FCO00FFD70O4O60O180AE0O403FFF00OC0' ); 
, '040000000B80040000000F00040000000E0007FFFFFFFC00' ); 



, '0007FFFFFC00000800000C00001000001C00002000003400' ); 
. •004000006C0000FFFFFFD40000800000ACOO0OBFFFFED400' ); 
, •0OA00002ACO0O0A07F02D40000A04102AC0O0OA07F02D400' ); 
. ■OOA00002ACOOOOA08082D40000AOFF82ACOOOOA00002D400' ); 
, 'OOA00002ACOOOOBFFFFED40000800000ACOOOOBFFFFED400' ); 
:. •OOA00002ACOOOOA07F02D40000A04102ACOOOOA07F02D400' ); 
, •OOA00002ACOOOOA08082D40000AOFF82ACOOOOA00002D800' ); 
, •OOA00002BOOOOOBFFFFEE00000800000COOOOOFFFFFF8000' ); 



> '000000000000000000000000000000000000000000000000' ); 
, '000000000000000000000000000000000000000000000000' ); 
, '000000000000000000000000000000000000000000000000' ); 
. 'OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOIFFFFFFO' ); 
> '0000580000300000680000700000D80000D0003FFFFFF1BO' ); 
. '0020000013500020000016B000201FE01D50002010201ABO' ); 
, '00201FE01560002000001AC0002000001580002020101BOO' ); 
. •00203FF01600002000001C00002000001800003FFFFFFOOO' ); 
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PROCEDURE Drawicon(whlchicoah^v: integer); 
VAR srcBlts: BitMap; 

srcRect^dstRect: Rect; 
begin 

srcBi t s . baseAddr : =aicons [ whichlcon ]; 

srcBits . rowBy tes : «6; 

SetRect(srcBits .bounds^ 0, 0, 48, 32); 

srcRect : -srcBlts . txMids; 
\lstRect:=srcRect; 

Of f setRect(dstRect, rv v); 

CopyBits(srcBits> thePort" .portBlts, srcRect, dstRect, srcOr, Nil); 
END; 

PROCEDURE DrawStUff; 

VAR 1: INTEGER; 
tenpRect: Rect; 
myPoly: PolyHandle; 
myRgn: RgnHandle; 
myPattern: Pattern; 

BEGIN 
Stuff H@x(afnyPattera ' 8040200002040800 * ); 

terapRect :- thePort*.portRect; 
CllpRect(tenipRect); 
EraseRoundRect(teiipRect, 50, 20); 
FranieRoundRect(teni)Rect, 30, 20); 

{ draw Vm horizontal lines across the top } 

HoveTo(0, 18); 

LlneTo(719,18); 

MoveTo(0,20); 

LlneTo(719,20); 

{ draw divider lines > 

MoveTo(0, 134); 
LineT0(719, 134); 
HoveTo( 0,248); 
LlneT0(719,248); 
hOVeTo(240,21); 
LlneTo(240,363); 
HoveTo(480,21); 
LineTo(480,363); 
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{ draw title } 

TextFont(O); 

MoveTo(210. 14); 

DrawStringCLook wtet you can draw with QuickDraw'); 



{ draw text sanples } 

rioveTo(80, 34); DrawString( ' Text ' ); 

TextFace([bold}); 

MoveTo(70^ 55); DrawString( ' Bold ' ); 

TextFaceC [ italic ] ); 

MoveTo(70^ 70); DrawString( ' Italic ' ); 

TextFaceC [underline ] ); 

MoveTo(70, 85); OrawString( * Underline ' ); 

TextFace([outline]); 

MoveTo(70^ 100); DrawString( ' Outline ' ); 

TextFace( [ shadow ) ); 

MoveTo(70, 115); DrawStringC ' Shadow ' ); 

TextFaceC []); { restore to normal } 



{ draw line samples 

rioveToC330, 34); DrawStringC ' Lines * ); 

MoveToC280, 25); LineC 160, 40); 

PenSizeC3,2); 

MoveToC280, 35); LineC 160, 40); 

PenSizeC6, 4); 

MoveToC280,46); LineC 160, 40); 

PenSizeCl2,8); 

PenPatCgray); 

HoveToC280, 61 ); LineC 160, 40); 
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PenSi2e(15,10); 
PenPat (myPattern ); 
MoveTo(28a 80); Line( 160, 40); 
PenNormal; 

{ draw rectangle sanples } 

MoveTo(560, 34); OrawString( ' Rectangles ' ); 

SetRect(teif|)Rect, 510, 40, 570, 70); 
F ranieRect ( tenpRect ); 

Of f setRect(tempRect, 25, 15); 
PenSize(3, 2); 
EraseRect ( teinpRect ); 
FrameRect ( teniaRect ); 

Of f setRect(tenpRect, 25, 15); 
PalntRect ( tenpRect ); 

Of f setRect(tempRect, 25, 15); 
PenNormal; 

FlllRect(tenpRect, gray); 
FrameRect ( tempRect ); 

Of f setRect(tempRect^ 25, 15); 
FillRect(tenpRect, myPattern); 
FrameRect (tempRect ); 

{ draw roundRect samples } 

MoveToC 70, 148 ); DrawString( ' RoundRect s ' ); 

SetRectrtenpRectv 30, 150. 90. 180); 
FrQm©Rou»TdPteot(toinpRoot, 30, 20); 

Of f setRect(teiipRect, 25, 15); 
PenSi2e(3,2); 

EraseRoundRect(tempRect, 30, 20); 
FrameRoundRectCtempRect, 30, 20); 

Of f setRectCtenpRect, 25, 15); 
PaintRounctftect(tefflpRect, 30, 20); 
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Of f setRectCtenpRect^ 25, 15); 
PenNormal; 

FillRoundRectCtenpRect, 30, 20, aray); 
FrameRounclRect(ternpRect, 30, 20); 

0ffsetRect(teinpRect,25, 15); 
FillRounclRect(tejrpRect, 30, 20, myPattern); 
FraineRounclRect(tempRect, 30, 20); 

{ draw bit image sanples } 

MoveTo(320, 148); DrawString('Bit Images"); 

Drawlcon(0,266,156); 
DrawIcon( 1,336, 156); 
DrawIcon(2, 406, 156); 
DrawIcon(3, 266, 1%); 
DrawIcon(4, 336, 196); 
DrawIcon(5, 406, 1%); 

{ draw Wedge samples } 

MoveTo(570, 148 ); DrawString( ' Wedges * ); 

SetRectCtempRect, 520, 153, 655, 243); 
FillArc(tempRect, 135, 65, dkGray); 
FillArc(tem|3Rect, 200, 130, myPattern); 
FillArc(tenpRect, 330, 75, gray); 
FraffleArc(tempRect, 135, 270); 
Of f setRect(tempRect, 20, 0); 
PaintArc(tefnpRect, 45, 90); 

{ draw polygon sanples } 



HoveTo(80, 262); DrawString( ' Polygons ' ); 
myPoly:=OpenPoly; 

MoveTo(30,290); 

LineTo(30,280); 

LineTo(50,265); 

LineTo(90,265); 

LineTo(80,280); 

LineTo(95,290); 

LineTo(30,290); 
ClosePoly; { end of definition } 
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FraraePoly (myPoly ); 

Of f setPoly(myPoly^ 25, 15); 
PenSize(3,2); 
ErasePoly (myPoly ); 
FrainePoly(rryPoly); 

Of f setPoly(inyPoly, 25. 15); 
PaintPoly (myPoly ); 

Of f setPoly(myPoly. 25, 15); 
PenNormal; 

FillPoly(myPoly, gray); 
FraraePoly(myPoly); 

Of f setPoly(myPoly, 25, 15); 
FillPoly (myPoly, myPattern); 
FraraePoly (myPoly ); 

KillPoly (myPoly); 



{ demonstrate region clipping } 

HoveTo(320, 262); DrawString( ' Regions ' ); 

myRgn : =N©wRgn; 
OpenRgn; 
ShowPen; 

SetRect(tempRect, 260, 270, 460, 350); 
FrameRounclRect(tefnpReot, 24, 16); 

HoveTo(275, 335); { define triangular hole } 
LineTo(325, 285); 

LineTo(275, 335); 

SetRect(tempRect, 365, 277, 445^ 325); { oval hole } 
FrameOval ( tempRect ); 

HidePen; 
CloseRgn(myRgn); { end of definition } 

SetClip(myRgn); 
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FOR i:=0 TO 6 DO { draw stuff inside the clip region } 
BEGIN 

MoveTo(26a280+12*i); 

DrawStringC Arbitrary Clipping Regitxis'); 
EhD; 

ClipRect(thePort* . portRect ); 
Di^sdRgi(nyRgn); 

{ draw oval samples } 

MoveTo(580, 262); DrawString( ' Ovals ' ); 

SetRect(teiHDRect 510, 264, 570, 294); 
FrameOval ( tenpRect ); 

Of f setRectCtempRect, 25, 15); 
PenSi2e(3, 2); 
EraseOval ( tanpRect ); 
FrameOval ( tempRect ); 

Of f setRect(teifpRect, 25, 15); 
PaintOval(tefflf:tflect); 

Off setRect(tempRect, 25, 15); 
PenNormal; 

FillOval(tenf)Rect, gray); 
FrameOval (tempRect); 

Off setRectCtempRect, 25, 15); 
FillOval(tefflpRect, myPattern); 
FrameOval ( tenpRect ); 
EhD; { DrawStuff } 



E-99 



Pascal Refiswnce Ml&%ial QjickDraw 

BEGIN { main program } 
{ Initialization - Generic to all applications using QuickDraw } 
QDInit(iBheapBuf, aheapBuf[ 10000]^ sHeapFull); { Must do this once at 

beginnir^ } 
C^3er#>ort(«9myPort); 
PaintRect(thePort".portRect); { Paint grey background } 

Inltlcons; 
DrawStuff; 
Tone(2000, 500); { Beep tone of (1/2000)*10"6 == 500 cycles/sec for 

500 milliseconds } 
ReadLn; { Wait until RETURN entered before terminating program } 
END. 
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E.14w2 Boxes 

The program Boxes (in the file QD/Boxes.TEXT) uses the Graf3D routines to 
draw random three-dimensional boxes on a grid, as shown in Figure E-27. 




Figure E-27 
Boxes 

The file GJD/M/Boxbs.TEXT is an exec file that can be used to rebuild this 
sample program. Disregard any warning messages from the linker about name 
conflicts- 
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PROGRAM Boxes; 

{ Sample program illustrating use of the 6raf3D unit by drawing random 
3D boxes on a grid. } 

USES 

{$U QD/QuickDraw.OBJ } QuickDraw, 

{$U QD/Graf3D.oa3 } Graf 30, 

{$U QD/QDSupport.OBJ } QOSupport, 

CONST boxCount = 15; 



TYPE Box3D=REC0RD 




ptl: Point3D; 




pt2: Point3D; 




dist: REAL; 


1 


END; 


VAR 




heapBuf: 


ARRAY[0..8192] OF INTEGER; 


GPortl: 


GrafPort; 


6Purt2: 


Port3d; 


myPort: 


GrafPtr; 


myPort3D 


: Port3DPtr; 


boxArray 


: ARRAY [0..bOXCOunt] OF Box3D; 


nBoxes: 


INTEGER; 


1: 


INTEGER; 



{16k bytes} 



FUNCTION HeapError<h2: QDPtr; bytesNeeded: INTEGER): INTEGER; 
{ this procedure gets called when the heap zone is full } 
BEGIN 

WRITELNCThe heap is full. The program must now terminate! '); 

HALL- 
END; 



FUNOTION Di8tanoe(ptl,pt2! P0INT5D): m.H.; 

VAR dx,dy,dz: REAL; 
BEGIN 

dX:=pt2.X - ptl.X; 

dy:-pt2.Y - ptl.Y; 

dz:=pt2.Z - ptl.Z; 

Distance :=SORT(dx*dx + dy*dy + dz*dz); 
END; 
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PROCEDURE MakeBox; 



VAR myBox: 


B0X3D; 
INTEGER; 


pl,p2: 

myRect: 

testRect: 


Point3D; 

Rect; 

Rect; 


BEGIN 




pi. X: -Random mod 70-15; 


pl.y;=RandQm mod 70 -10; 


pl.2:»0.0; 
p2.X:=pl.X + 
p2.y:=pl.y * 
p2.Z:=pl.2 + 


10 * ABS(Random) MOO 30; 
10 * ABS(Random) MOD 45; 
10 + ABS(Random) MOD 35; 



{ reject tx)x if it intersects one already in list } 
SetRect(myRect, ROUND(pl .x), ROUND(pl .y ), R0UND(p2 .x)^ R0UND(p2 .y ) ); 
FOR i:=0 TO nBoxes-1 DO 
BEGIN 
WITH tJoxArray[i] DO 
SetRect( testRect, ROUND(ptl .x), ROUND(ptl .y ), 
R0UND(pt2.x), R0UND(pt2.y )); 
IF SectRect(myRect, testRect, testRect) THEN EXIT(MakeBox); 
END; 

myBox.ptl:=pl; 
myBox.pt2:»p2; 

{ calc mic^int of box arKJ its distarrce from the eye } 

pl.X:=(pl.x + p2.x)/2.0; 

pl.y:=(pl.y * p2.y)/2.0; 

pl.Z:=(pl.2 + p2.z)/2.0; 

Transform(pl,p2); 

myBox. dist:=Distance(p2,myPort3D". eye); { distance to eye } 

i:=0; 

boxArray[nBoxes3.dist:-myBox.dist; { sentinel } 

lilHILE royBox.dist > boxArrayEiJ.dist DO i:=i+l; {insert in order of dist} 
FOR j:-nBoxes DOWNTO i*l DO boxArray[ j]:-boxArray[ j-1]; 
boxArray [ i ] : =myBox; 
n^xes : =nBoxes+ 1; 
END; 
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PROCEDURE DrawBox(ptl,pt2: Point30); 
{ draws a 30 box with shaded faces. } 
{ only shades cxirrectly in one direction } 
VAR tenpRgn: RgnHandle; 

BEGIN 
tenpRgn:=Ne«Rgn; 
OpenRyi; 

MoveTo30(ptl.x,ptl.y,ptl.2); { front face, y=yl } 

LlneTo30(ptl .X, ptl .y, pt2 .z); 

LineTo3D(pt2 . x, ptl .y, pt2 . z); 

LineTo30(pt2 , x^ ptl ,y, ptl . z); 

LineTo30(ptl -x, ptl .y, ptl .z); 
OloseRgn(teinpRgn); 
FillRgnCtempRgn, white); 

OpenRgn; 

MoveTo30(ptl.x,ptl.y,pt2.z); { top face, z=z2 } 

LineTo3D(ptl . x, pt2 .y, pt2 . z); 

LineTo3D(pt2.x, pt2,y, pt2.z); 

LineTo3D(pt2 . x, ptl . y, pt2 . z ); 

LineTo3D(ptl . x, ptl .y, pt2 .z); 
CloseRgn(teiipRgn); 
FillRgn(teii^gn, gray ); 

Opertflgn; 

MoveTo3D(pt2.x,ptl.y,ptl.2); { right face, x=x2 } 

LineTo30(pt2 . x, ptl .y, pt2 . z ); 

LineTo3D(pt2.x, pt2.y, pt2.2); 

LineTo3D(pt2 . x, pt2 .y, ptl . z); 

LineTo30(pt2.x, ptl .y, ptl .z); 
CloseRgn(tefnpRgn); 
FillRgnCtenpRgn, black); 

PenPat(white); 

MoveTo3D(pt2.x,pt2.y,pt2.z); { outline right } 

LxneTo3D(pt2.)C pt2.y^ ptl .z); 

LineTo30(pt2 . >^ ptl .y, ptl .z); 

PenNormal; 

OisposeRgn(tenpRgn); 
END; 
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BEGIN { main program } 
{ Initialization - Generic to all applications using QuickDraw } 
QOInit(aheapBuf, aheapBuf [8192L sfieapError); { Must do this once at 

begiming ) 

myPort := aGPortl; 
Oper#»ort(myPort); 
myPort3D := »GPort2; 
0pen3DPort(myPort30); 

ViewPortCmyPorf.portRect); { |xit the image in this rect } 

LookAt(-100,75^100, -75); { aim the camera into 3D space } 

Vie«Angle(30); { choose lens focal length } 

Identity; Roll(20); Pitch(70); { roll and pitch the plane } 

PenPat( white); 
BackPat(black); 
EraseRect(myPort* .portRect); 

FOR i:=-10 TO 10 DO 
BEGIN 

rtoveTo3D(i*10^ -100^ 0); 

LineTo3D(i*10, +100, 0); 
END; 

FOR i:=-10 TO 10 DO 
BEGIN 

MoveTo3D(-100, i*10, 0); 

LineTo3D(+100, i*10, 0); 
END; 

r^xes:=0; 

REPEAT MakeBox; UNTIL nBoxes=boxCount; 
FOR i:=nBoxes-l OOWNTO DO 
DrawBox(toxArray [ i ] . pt 1, boxArray [ i ] . pt2 ); 

Tone(20G0, 500); {Beep tone of (1/2000)*10*6 == 500 cycles/sec for 

500 milliseconds } 
ReadLn; { Wait until RETl^ entered before terminating prc^ram } 

END. 
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E.15 QOSupport 

The QOSupport unit (in the file QD/QDSupportTEXT) provides the 
initialization that you need to use QuickDraw in the QDlnlt procedure, as well 
as procedures for simplified access to mouse tracking^ the mouse button^ and 
sound generation, and useful definitions of font numbers. For more detailed 
Information on mouse-handling routines and sound, refer to /Appendix F, 
Hardware Interface. 

UNIT QOSupport; 

INTERFACE 

USES 



{$u QD/Unitstd.OBJ } unitstd. 


{$U OD/UnitHz.OBJ 


} UnitHz, 


{$U QD/Hardware.OBJ } Hardware, 


{$U QO/Fontmgr.OBJ } Fontmgr, 


{$U QO/QuickOraw.OBJ } QuickDraw; 


CONST 

f 


_ Crnn-t- Ml 1 


mt-.<-.«><^ ^ 


l 


rOnX NUiiiJcx;) / 


FTllelZ 


= 4; 


{proportional 


FTilelS 


= 5; 


(proportional 


FTile24 


= 6; 


{proportional} 


FPlSTlle 


= 7; 


(Monospaced - 8 lines/inch & 15 chars/inch} 


FPlZTlle 


= 8; 


{Monospaced - 6 lines/inch a 12 chars/inch} 


FPlOTlle 


= 9; 


(Monosjaaced - 6 lines/inch & 10 chars/inch} 


FCentlZ 


= 10; 


{proportional} 


FCentlS 


= 11; 


(proportional 


FCent24 


= 12; 


{proportional} 


FPl2Cent 


= 13; 


(Monospaced - 6 lines/inch & 12 chars/inch} 


FPlOCent 


= 14; 


(Monospaced - 6 lines/inch & 10 chars/inch} 


FP20Tile 


= 19; 


(Monospaced} 
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PROCEDURE QDInit(startPtr, limitPtr: QOPtr; ErrorProc: QOPtr); 
{ QOInit: Initializes QuickDraw unit by setting up its heap 

zone, global vars, cursor, and the Font Manager it 

calls on. } 

PROCEDURE GetMouse(VAR pt: Point); 

{ GetMouse: Returns the current mouse location in the lojal 
coordinates of the current grafPort. } 

FUKCTION MouseButton: BOOLEAN; 

{ MouseButton: Returns TRUE if the mouse button is currently held 
down, otherwise FALSE. } 

PROCEDURE Tone(waveLength, duration: Longint); 

{ Tone: Produces a square wave tone of the specified 

wavelength (microseconds) for the specified duration 

(milliseconds). } 
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E16 Glossary 

bit image: A collection of bits in memory that have a rectilinear represen- 
tatioa The Lisa screen is a visible bit image. 

bitmap: A pointer to a bit image, the row width of that image, and its 
bouixlary rectangle. 

boundary rectangle: A rectangle defined as part of a bitmap, which encloses 
the active area of the bit image arKi imposes a coordinate system on it Its 
top left comer is always aligned around the first bit in the bit image. 

camera eye: A concept in three-dimensional graphics: the point of view and 
the viewing angle in which an c*)Ject spears, independent of the dbjecVs 
coordinates. 

character style: A set of stylistic variations, such as bold, italic, and 
underline. The empty set indicates normal text (no stylistic variations). 

clipping: Limiting drawing to within the bounds of a particular area 

clipping region: Same as clipRgn. 

clipRgn: The region to which an ^jplication limits drawing in a grafPort, 

coordinate plane: A two-dimensional grid. In QuickDraw, the grid coordinates 
are integers ranging from -32768 to +32767, and all grid lines are infinitely 
thin. 

curscff: A 16-by- 16-bit image that appears on the screen and is controlled by 
the mouse. 

cursor level: A value, initialized to when the system is booted, that keeps 
track of the number of times the cursor has been hiddea 

empty: Containing no bits, as a shape defined by only one point 

font The complete set of charactere of one typeface, such as Century. 

frame: To draw a shape by drawing an outline of it 

global coordinate system: The coordinate system based on the top left comer 
of the bit image being at (0,0). 

GrafSD: A three-dimensior^ graphics unit that calls QuickDraw routines. 

grafPort A complete drawing environment, including such el«TTents as a 
bitmap, a subset of it in which to draw, a character font, patterns for drawing 
and erasing, and other pen characteristics. 

grafPtr: A pointer to a grafPort 

handle: A pointer to one master pointer to a dynamic, relocatable data 
structure (such as a region). 

hot:^30t The point in a cursor that is alibied with the mouse position. 

keirt To stretch part of a character back under the previous character. 
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local cooiifinate system: The coordinate system local to a grafPort imposed 
by tf« bounc^ry rectangle defined in its bitm^. 

rrdssing symboU A character to be drawn in case of a request to draw a 
character that is missing from a particular font 

pattern: An 8-by-8-bit image^ used to define a repeating design (such as 
stripes) or tone ^uch as gray). 

pattern transfer mode: Gne of eight transfer modes for drawing lines or 
shqaes with a pattern. 

picture: A saved sequence of QuickDraw drawing commands (and, optionally, 
picture corrvrents) that yew can play back later with a single procedure call; 
also, the image resulting from these commands. 

picture comments: Data stored in the definition of a picture which does not 
affect VnQ picture's appearance but may tie used to provide additicnal 
information about the picture when it's played back. 

picture frame: A rectangle, defined as part of a picture, which surrounds the 
picture and gives a frame of reference for scaling when the picture is drawn. 

pixel: The visual representatiwi of a bit on the screen (white if the bit is 0, 
black if it's 1\ 

point The intenection of a horizontal grid line and a vertical grid line on 
the coordinate plane, defined by a horizontal and a vertical coordinate. 

polygon: A sequence of connected lines, defined by QuickDraw line-drawing 
coiTvnands. 

port QrafPort or Port3D. 

Port3D: A data structure in Graf3D that maps three-dimensional coordinates 
into a two-dimensional QuickDraw grafPort. 

PoTt3DPti: A pointer to a Port3D. 

portBits: The bitmap of a grafPort 

portBitsJtxxjnds: The boundary rectangle of a grafPort's bitmap. 

portRect A rectangle, defined as part of a grafPort, which encloses a subset 
of the bitm^ for use by the grafPort 

region: An arbitrary area or set of areas on the coordinate plane. The 
outline of a region should be one or more closed loops. 

row width: The niflnnber of bytes in each row of a bit image. 

scale: To shrink or expand by a specified factor. 

solid: Filled in with any pattera 

source transfer mode: One of eight transfer modes for drawing text or 
transferring any bit image between two bitmaps. 
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style: See character style. 

thePort: A global variable that points to the current grafPort 

thePort30: A global variable that points to the current Port3D. 

transfer mode: A specification of which twolean qperation QuickDraw should 
perform wTren drawing or wr«n transferring a bit imsK|e from one bitmap to 
another. 

translate: To move in three-dimensional space by a specified amount 

transfDimation matrix^ Same as xForm matrix. 

viewing pyrantfd: The portion of three-dimensional space that a camera eye 
can see. The pyramid's apex is the point of the camera eye; its base is the 
viewRect in a Port3D. 

visRgn: The region of a grafPort which is actually visible on the screea 

xFoim matrix: A 4x4 matrix that holds an equation to transform points 
plotted in three-dimensional coordinates into two-dimensional screen 
coordinates. 



E-110 



Appendix F 
Hardware Interface 



F.1 The Mouse . F-1 

F.1.1 MouseLocation F-1 

F.1.2 Mouse L^xtete Frequency F-1 

F.1.3 MouseScaling F-1 

F.Lft MouseOctometer F-2 

F^ TheCursor F-2 

F,2.1 Cursoi/Mouse Tracking F-3 

F.2.2 TheBusy Cursor F-3 

F.3 The Display Screen F-4 

F.3.1 Screen Contrast , F-ft 

F.3^ Automatic Screen Fading F-ft 

F.4 The Speaker F-5 

F3 The Keyboard F-5 

F.5.1 Keyboard Identification F-7 

F.5.2 KeyboardState F-8 

F.5.3 Keyboard Events F-8 

F.5.4 Dead Key Diacriticals F-10 

F.55 Repeats F-11 

F^ The Kfidosecond Timer F-11 

F.7 The Mimsecond Timer F-12 

F.8 Date and Time F-12 

F.9 Time Stamp F-12 

F.10 InteifaceoftheHardwareUhit F-13 



Hardware Interface 



The hardware interface asftware provides an interface for accessing and 
controlling several parts of the Lisa hardware. The hardware/software 
caf)abilities addressed include the mouse^ the cursor, the display, the contrast 
control, the speaker, both mdecoded and decoded keytxiard access, the micro- 
second and millisecond timers and the hardware clock/calendar. 

This appendix contains Pascal procedure and function declarations interleaved 
with text describing them. Pascal type declarations and a summary of the 
function and procedure declarations can be found in Section F.IO, Interface of 
the Hardware Unit 

Programs using this unit stuuld be ccnipiled against the file cp/Hardware.CBJ 
and linked to the file Cp/HWIntL.OBJ. 

F.l The Mouse 
F.1.1 Mouse Location 

Procedure MouscLocaticm (var x: Pixels; var y: Pixels); 

The mouse is a pointing device used to indicate screen locations. 
MouseLocation returns the location of the mouse. The X-coordinate can range 
from to 719, and the Y-coordinate from to 363. The initial mouse 
location is 043. 

F.1.2 Mouse Update Frequency 

Procedure MouseMpdates (delay: Milliseconds); 

Software knowled^ of the mouse location is ifxjated periodically, rather than 
continuously. Ttie frequency of these updates can be set by calling 
MouseUpdates. The time between updates can range from milliseconds 
(continuous updating) to 28 milliseconds, in intervals of 4 milliseconds. The 
initial setting is 16 milliseconds. 

F.L3 Mouse Scaling 

Procedure MouseScaling (scalejBoolean); 

Procedure MouseThresh (thresholdt nxels); 

Tt^ relationship between physical mouse movements and logical mouse move- 
ments is not necessarily a fixed linear mappir^. Three alternatives are 
available: 1) unsealed, 2) scaled for fine movement and 3) scaled for coarse 
movement Initially mouse movements are unsealed. 

When mouse movement is unsealed a horizontal mouse movement of x units 
yields a change in the mouse X-coordinate of x pixels. Similiarly, a vertical 
movement of y units yields a change is the mouse Y-coordinate of y pixels. 
These rules apply indqpendent of the speed of the mouse movement 
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When mouse movement is scaled horizontal movements are magnified by 3/2 
relative to vertical movements. This is lo compensate for the 2/3 aspect 
ratio of pixels on the screen. When scaling is in effect a distinction is made 
between fine (small) movements and coarse Oarge) movements. Fine move- 
ments are slightly reduced, while coarse movements are magnified. For scaled 
fine movements^ a horizontal mouse movement of x units yields a (^wige in 
the X-coordinale of x pixels, but a vertical movement of y units yields a 
change of (2/3)*y pixels. For scaled coarse movements, a horizontal movement 
a x units yields a change of (3/2)*x pixels, while a vertical movements of y 
units yields a change of y pixels. 

The distinction between fine movements and coarse movements is determined 
by the sum of the x and y movements each time the mouse location is 
updated. If this sum is at or below the thre^xjlci the movement is considered 
to be a fine moverrwnt Values of the threshold range from (which yields all 
coarse movements) to 256 (which yields all fine movements). Given the 
default mouse upckting frequency, a threshold of about 8 (threshold's initial 
setting) gives a comfortable transition between fine and coarse movements. 

MoisseSi^ing enables and disables mouse scaling. MouseThresh sets the 
threshold between fine and coarse mo>^ments. 

F.jL4 Mouse Odometer 

Function MouseOdometen ManyPixels; 

In order to properly specify, design and test mice, it's important to estimate 
how far a mouse moves during its lifetime. MouseOdometer returns the sum 
of the X and Y movements of the mouse since boot time. The value returned 
is in (unsealed) pixels. There are 180 pixels per inch of mouse movement 

f2 The Cursor 

Procedure Cursorlmage (hot)G Pixels; hotY: Fixels; height: CXirsorHelght; data 
CursoiPtr; mask: CursoiPtr); 

The cursor is a small image that is displayed on the screen. Its shape is 
specified by two bitmaps, called d&ta and mask These bitmaps are 16 bits 
wide and from to 32 bits high. The rule used to combine the bits already 
on the screen wliii the data and mask is 

screen <- (screen and (not maesk^ xor data. 

The effect is that white areas of the screen are replaced with the cursor 
data Black areas of the screen are replaced with (not mask) xor data If the 
data and mask bitmaps are identical, the effect is to or the data onto the 
screen. 

The cursor has both a location and a hot-pot The location is a position on 
the screai, with X-coordinates of to 719 and Y-coirdinates of to 363, 
The hot;p)t is a position within the cursor bitmaps, witfi X- and Y-coordi- 
nates ranging from to 16. The cursor is display^ on the screen with its 
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hotspot at its locatioa If Ue cursor's location is near an edge of tfie screen, 
the cursor image may be partially or completely off the screen. 

Most cursor operations can be performed by calling the SetCursor, httdeGXirsor, 
ShowCXirsor, and GbscureGXirsor proceckires defined by QuickDraw (see Section 
E.9.2, Cursor-Handling Routines). Additional capabilities are provided by the 
Hardware Interface routines described below. 

The Cursorlmage procedure is used to specify the data bitmap, mask bitmap, 
height and hot^t of the cursor. Initially the cursor data and mask bitmaps 
contain all zeros, which yields a blank (invisible) cursor. The initial hotspot is 
0,0. 

FJLl Cursor/Mouse Tracking 

Procedure CursorTracking (track: Boolean); 

Procedure CursoiLocation (x: Pixels; y: Pixels); 

CursorTracking enables and disables cunor tracking of the mouse. When 
tracking is enabled, the cursor location is changed to ti% mouse location each 
time the mouse moves. Setting the cursor location by calling CursorLocation 
will have no effect; the cursor sticks with the mouse. 

Vfl^n tracking is disabled, the mouse legation and cursor location are inctepen- 
dent Calling CursorLocation will move the cursor; moving the mouse will not 

V^flien tracking is first enabled (i.e., on eash transition from disabled to 
enabled) the mouse location is modified to equal the cursor location. There- 
fore, en^ling tracking ckaes not move the cursor; it drois nrodify the majse 
location. Initially tracking is enabled. 

¥22 The Busy Cursor 

Procedure Busybnage (hotX: Pixels; hotY: Pixels; height: CursoiHeight; data: 
CursorPtr; mask: CursorPtr); 

Procedure BusyOelay (delay: Nttlliseconds); 

/plications may desire to display a busy cursor (e.g., an hcxjrgls^) when an 
operation in progress requires nnore than a few seconds to complete. The 
Busylmage procedure is used to ^lecify the data bitmap, ma^ bitmap, height 
and hotspot of the busy cursor. 

A call to BusyOelay specifies that the normal cursor should currently be 
displayed, aid that display of the busy cunor should be ctelayed for the 
specified number of milliseconds. Stisseqi^nt calls to BusyOelay overricte 
previous calls, postponing display of tr« busy cursor. If no calls to BusyOelay 
occur for the specified nynrtoer of millisecmds, the busy cursor will be 
displayed intil Mtr next call to BusyOelay. 

Initially the busy cursor data and mask bitmaps contain all zeros, which yields 
a blank (invisible) cursor. The initial hots|M)t is OA The initial txjsy delay is 
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infinite^ that is, the busy cursor will not be displayed until BusyOelay is 
called 

F.3 T!ie Display Screen 

Pnx»dure ScreenSize (var x: Pixels; var y: Rxels); 

The display screen is a bit m^:ped di^lay; that is, each pixel on the screen 
is controlled by a bit in main memory. The display has 720 pixels horizontally 
and 364 lines vertically, and therefore requires 32,760 bytes of main memory. 
The screen size may be determined by calling ScreenSize. 

Function FiameCounter: Frames; 

The screen is redisplayed about 60 times per second. A fr&ne ccMiter is 
incremented between screen Lfwiates, at the vertical retrace interrupt The 
frame counter is an unsigned 32-bit integer which is reset to each time the 
machine is booted. FrameCounter returns this value. An application can 
synchronize with the vertical retraces by watching for changes in the value of 
this counter^ The frsune camter should rwt be used as a timer; use the 
millisecond and mircosecond timers instead. 

F3.1 Screen Contrast 

Function Contrast: ScreenContrast; 

Procedure SetContrast (contrast: ScreenContrast); 

The display's contrast level is under program control. Contrast values range 
from Q to 255 (^F), with as maxirmsm contrast and 255 as minimum. 
Contrast returns the contrast setting; SetContiast sets the screen contrast. 
Tr« low orcter two bits of the contrast valL« are i^xjred. Tire initial contrast 
value is 128 ($80X 

Procedure RampContrast (contrast: ScreenContrast); 

A sudden chgnge in the cmtrast level can te jarring to the user. 
F^mpCcntrast gradually c^ianges the contrast to the new setting over a pericxl 

r%4 «sHhru g4 *s% vcwnrinHI C!>«3Mmnif\riri| wya wff trof i iinrHB> «rTwrrM9hr44«if csltf 4l-M9Hn r'^snnrwp 4Haa 
\jf\ uft./^L^MV u i»Mi>wuini nji. ■ ^mjv « ibj^./oi imukvv i«»^i.v«ii la iMninM'Vf«VJMu«jry. w iwt ■ acjii i|j>i7 ur iw 

contrast using interrupt driven processing. 

F.3i.2 Ajtomatic Screen Fading 

Function DimContrast: ScreenContrast; 

Procedure SetOimContiast (contrast: ScreenContrast); 

The screen contrast level is automatically dimmed if no user activity is noted 
over a sjKcified jirerioj (usually several mirBJtes). This is done in order to 
preserve the screen pho^3her. COmContrast returns the contrast value to which 
the screen is dimmed; SeUDimCantr&Bt sets this value. The initial dim 
contrast setting is 176 ($80). 
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Function FadeOelay: Milliseconds; 

ProcedLne SetFadeOelay (delay: Milliseconds); 

The delay between Uie last user activity and dimming of trie screen is under 
software control. FadeOel^ returns the fade delay; SetFadeOelay sets it 
The actual delay will range from the specified delay to twice the specified 
delay. The initial delay period is five minutes. 

When the screen is dim, user interaction will cause the screen contrast to 
return to its normal bright level (determined by the Contrast and SetContrast 
routines defined above). Moving the mouse or pressing a key on the keyboard 
(e-g., SHIFT) is enough to trigger the screen brightening. Calling 
CursoiLocaUon or SetFadeOelay also indicates user activity. 

F.4 The Speaker 

Function \/oIume: SpeakerVolume; 

Procedure SetVolume (volume: SpeakerVolume); 

Procedure Ndise (waveLength: Microseconds); 

PiDceduie Silence; 

Procedure Beep (waveLength: Microseconds; duration: Milliseconds); 

The routines in this section provide square wave output from the Lisa speaker. 
The speaker volume can be set to values in the range (soft) to 7 (loud). 
Volume reads the volume setting; SetVolume sets it The initial volume 
setting is 4. 

Noise produces a sqtere wave of approximately the specified wavelength. 
Silence shuts off the square wave. The minimum wavelength is about 8 
microseconds, which corresponds to a frequency of 125,000 cycles per second, 
well above the audible range. The maximum wavelength is 8,191 micro- 
seconds, which corresponds to about 122 cycles per second. 

Noise and Siloice are called in pairs to start arei stop scpjare wave output In 
contrast. Beep starts square wave output which will automatically stop after 
the specified period of time. The effects of Noise, Silence and Beep are 
overridden by subsequent calls. 

F.5 The Keyboard 

Ttre routines in this sectityi provide an interface to the keyboard, the keypad, 
the mouse twtton and plug, the diskette buttons arsl insertion switches, and 
the power switch. Two interfaces are provicted, a pollable keyt)oard state end 
a queue of keyboard events. 

Three physical keyboard layouts are defined, the "Old US Layout" (with 73 
keys on the main keyboard and numeric keypad), the "Final US Layout" (76 
keys) and the "Eurqf«ar» Layout" (77 keys). Each key has been assigned a 
keyccxH which uniquely identifies the key. Keycode values range from to 
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127. Table F-1 defines the keycodes for the Tinal US Layout", using the 
legencte from the US Keytjoard. The "Old US Layout" has three less keys; jV 
Alpha Enter, and Right Option are not on the old keytward. The "European 
Layout" has one additional key, ><, with a keycode of $43. 

Two keys on the "Old US Layout" generate keycodes different from the 
corresponding keys on the "Final US Layout". To aid in compatibility, 
software changes the keycode for " * from $7C to $68, and the keywjde for 
Right Option from $68 to $«E. 

Table F-1 
Keycodes for Tinal US Layout" 



LOU 
t 


000 



001 
1 


010 
2 


Oil 

3 


100 
4 


101 
5 


110 
6 


111 
7 


QDOQ 







CLEAR 




— 


( 
9 


E 


A 


0001 
1 


DISK 1 
IMSE»TEO 




- 




+ 


) 



6 


2 


0010 
2 


DISif ! 
BUTTON 




^1 




\ 
\ 


U 


7 


3 


0011 
3 


DISK 2 
INSERTED 










I 


8 


$ 
4 


OIDD 
4 


DISK 2 
BUTTON 


f 


7 




P 


J 


% 
5 


1 
1 


0101 
5 


PARALLEL 
PORT 




8 




BACKSPACE 


K 


R 


Q 


0110 
6 


HOUSE 
BUTTON 




9 


\ 


ALPHA 
ENTER 


{ 
[ 


T 


S 


0111 
7 


HOUSE 
PLUG 




fil 






> 
3 


Y 


W 


lOQQ 
8 


POUER 
BUTTON 




4 




RETURN 


M 


#w 


TAB 


lOui 
9 






5 







L 


F 


z 


1010 
A 




; 


6 






f 


G 


X 


1011 
B 






LfJ 


■ 




" 


H 


D 


1100 
C 




; 


. 




7 
/ 


SPACE 


V 


LEFT 
OPTION 


1101 
D 




; 


2 


'■ 


1 


< 


C 


CAPS 
LOCK 


1110 
E 




: 


3 


\ 


RIGHT 
OPTION 


> 


B 


SHIFT 


1111 
F 




; 


NUHERIC 
ENTER 


': 







N 


« 
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F5.1 Keyboard Identification 

Function Keyboard: Keybdid; 

Function Legends: Keybdid; 

Procedure SetLegends 0d: KeybdIcQi; 

Lisa software supports a host of different keyboards. Each keyboard has three 
major attributes: manufacturer^ physical layout, and legencis. The chart 
below describes how these three attributes are combined to form a keyboard 
identi- fication number. The keyboards self Identify when the machine is 
turned on and when a new keyboard is attached. Keyboard returns the 
Identification number of the keyboard currently attached. Legends and 
SetLegends provide a means of pretending to have different legends, without 
physically replacing the keyboard. 

Keyboard identification numbers: 

7 65 4 3 2 1 D 

I Manufacturer I Layout \ Legends { 



Manufacturer: 


00 ~ 


APD (l.e., TKC) 


01 — 




10 ~ 

1 aumit' 


Keytronics 


L.ayiJUi.. 

00 ~ 


Old us (73 keys) 


01 — 




10 -- 


European (77 keys) 


11 — 

1 oumit'/i or 


Final US (76 keys) 


l_ci3rlRiii/l_cv 

$0F ~ 


Old US 


$26 - 


■ Swiss-German 


$27 - 


• Swiss-French 


$29 - 


• Portuguese 


$29 - 


• Spanish-Latin American 


$2A ~ 


Danish 


$2B - 


• Swedish 


$2C ~ 


Italian 


$2D ~ 


French 


$2E - 


• German 


$2F ~ 


UK 



(allocated for proposed software) 
(allocated for proposed software) 
(allocated for proposed software) 
(allocated for proposed software) 
(allocated for proposed software) 
(hardware not yet available) 
(hardware not yet available) 
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$3C ~ APL (allocated for proposed software) 

$3D — French-Canadian (allocated for proposed software) 

$3E ~ US-Dvorak (allocated for proposed software) 

$3F ~ Final us 

¥33. Keyt»ard State 

Function KeylsDown (key: KeyCap)[ Boolean; 

PiDceduiB KeyMap (var keys: KeyCapSetji; 

Low level access to the keyboard Is provided through a pollable keyboard 
state. This state information is based on the physical keycodes defined above. 
KeylsDown returns the position of a single specified key. KeyMap returns a 
128-bit map^ one bit for each key. A zero indicates the key is up^ a one 
indicates dowa For the mouse plug^ a zero indicates unplugged, a one indi- 
cates plugged in. Certain keys are not pollable; the corresponding bits will 
always be zero. These keys are the diskette insertion switches and buttons, 
parallel port and power switch. (The parallel port and mouse plug keys are 
unreliable across reboots on older hardware.) 

F.5.5 Keyfx)arti Events 

The hardware interface provides a queue of keyboard events. The events in 
the input queue are generally key down transitions. Each event contains the 
following information: 

Keycode ~ physical key 

ascH ~ ASCII interpretation of this key 

state ~ caps-lock, shift, option, %, mouse button and repeat 

mousex ~ x-coordlnate of the mouse v/hen the key was pressed 

mouseY ~ Y-coordinate of the mouse when the key was pressed 

time ~ value of the millisecond timer when the key was pressed 

Keycxxle — Keycodes are defined in Table F-l, above. 

Ascil — The ASCII Interpretation of keys depends on the state of the caps- 
lock, shift and option keys. Six interpretations are associated with each 
different keyboard layout: 

normal 

caps-lock 

shift or both shift and caps-lock 

option 

option with caps-lock 

option with shift or both shift and caps-lock 
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In most cases the ASCII value returned is obvious. The table below lists the 
cases that aren't so obvious. 

Disk 1 Inserted 

Disk 1 Button 

Disk 2 Inserted 

Disk 1 Button 

Power Button 

Mouse Button (down) 

Mouse Plug (in) 

Mouse Button (up) 

Mouse Plug (out) 

Enter 

Backspace 

Tab 

Return 

Clear 

Left 
Right 

Up 

Down 

Space 

State ~ A 16-bit word is used to return the state of several keys with each 
event Each bit represents one or more keys; a zero indicates that all of the 
keys are up^ a one indicates that at least one of the keys is dowa An 
additional bit indicates, if it is a one, that the event was generated by 
repeating the previous event The following bits of state are currently 
assigied: 

bit 0: caps-lock 

bit 1: left or right shift 

bit 2: left or ri^t option 

bit 3: i key 

bit 4: mouse button 

bit 5: this event is a repeat 

Certain keys never generate events. These keys are caps-lock, both shift 
keys, option keys, and the ^ key. The mouse button generates events on both 
the down and up transitions. Down transitions have an ascii value of 0, up 
transitions 1. The mouse plug also generates two different events. When the 
mouse is plugged in an event with an ascii value of is returned, when it is 
unpluc^ied a value of 1 is returned. 
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Function KeytxFeek (repeats: Boolean; index KeytxJQindex; var event: 
KeyEvent): Boolefm; 

KeytxPeek is used to examine events in the keytjoard queue, without removing 
them from the queue. The fint input parameter indicates whether repeats are 
desired. The second parameter is the queue index. The first output para- 
meter indicates whether the specified queue entry contains an event To 
examine an entire queue, first call KeybdPeek with a queue index of 1. If an 
event is returned, call it again with a c^ue index of 2, etc. 

Function KeybdEvent (repeats: Boolean; wait: Boolean; var event: KeyEvent^ 
Booleerv 

KeybdEvent is used both to determine if a keyboard event is available, and to 
return the event if one is available. The event is removed from the queue. 
KeybdEvent returns a boolean result which is true if an event is returned. 
The fint parameter to KeybdEvent is used to indicate if the caller will 
accqpt repeated events on this call. The second parsmeter indicates if the 
fmctions should wait for an event if one is not irranediately available. 

F3.4 Dead Key CMacilticals 

Many languages employ diacritical marks on certain letters. Several of the 
required diacritical mark-letter combinations appear on Eurqsean keyboards, 
but others do not. The combinations shown in the table below may be typed as 
a two-key sequence, by first typing the dead key diacritical (which has no 
immediate effect), and then typing the letter. Dead key diacriticals appear on 
keyboard legends as the diacritical mark over a dotted square or hollow box. 



circumflex ^ ~ a 


e 1 u 


grave accent ~ a 


k \ 6 


tilde " — a 


m S 


acute accent — a 


e^ i 6 


umlaut '* ~ aA 


e T oduO 



A dead key diacritical followed by a letter which appears in the table above 
yields the corresponding character. The event that is generated contains the 
keycode, state, mouse location and time that correspond to the letter, but the 
ASGI! value of the letter-diacritical combination. A dead key diacritical 
followed by a space yields just the diacritical mark. The event contains the 
keycode, state, mouse location and time corresponding to the space, but the 
ASCII value of the diacritical mark. Finally, a dead key diacritical followed 
by any other character (i.e., not a space or defined letter) yields the diacrit- 
ical mark followed by the other character. 

diacritical, defined letter ~> foreign character 

diacritical, space ~> diacritical 

diacritical, oVnex character ~> diacritical, other character 
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F53 Repeats 

Most keys, if held down for an extended period of time, may generate 
multiple events (repeats). The keys that are not repeatable are caps-lock, 
both shifts, both options, the # key, the diskette insertion switches and 
diskette buttons, parallel port, the mouse button and plug, and the power 
button. Several conditions must be satisfied before a repeat is generated. 
These conditions are as follows: 

1. KeybdPeek or KeybdEvent is called with lepeatsOesiied tn». 

2. The keyboard event queue is empty. 

3. The key returned in tr« last event is still down. 

4. No down transitions have occurred since the last event 

5. The key is repeatable. 

6. Enough time has el^sed. 

Repeats generate events with the following attributes: 

keycode — original keycode 

ascii ~ ori^nal ASCII interpretation 

state ~ original position of the caps-lock, shift, etc. 

mouseX ~ revised X-coordinate of the mouse 

mouseY — revised Y-coordinate of M^ mojse 

time ~ revised value of tf« milliSKJond tirrer 

Procedure RepeatRate (var initial: HUUSeconds; var subsequent: Milliseconds); 

Procedure SetRepeatRate (ir^tiak MiUiSecands; subsequent: MiUiSeconds); 

The repeat rates can be read and set by calls to RepeatRate and 
SetRepeatRate. The rates include an initial delay, which occurs prior to the 
fint repetition, aid a sitoseqtent delay, prior to additional repetitions. They 
are both in units of milliseconds. The default repeat rates are 400 
milliseconds initially and 100 milliseconds subsequently. 

F.6 The l^crosecond Timer 

Function MicioTimen Nttcroseconds; 

The MicroTimer function simulates a continuously running 32-bit counter 
which is incremented every microsecond. The timer is reset to eac^ time 
the madiire is booted. The timer changes sign about once every 35 minutes, 
and rolls over about every 70 minutes. 

The microsecond timer is desigr«d for performance measurements. It has a 
resolution of 2 microseconds. Calling MicroTimer from Pascal takes about 135 
microseconds. Note that internet processing will have a major effect on 
microsecond timings. 
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F-7 The Millisecond Timer 

Function Timen Milliseconds; 

The Timer amction simulates a continuously arming 32-bit counter which is 
incremented every millisecond. The timer is reset to each time the 
machine is booted. The timer changes sign dxxit once every 25 days, and 
rolls over about every 7 weeks. 

The millisecond timer is designed for timing user interactions such as mouse 
clicks and repeat keys. It can also be used for performance measurements, 
assuming that millisecond resolution is sufficient 

F.8 Date and Time 

Praceduie DateTlme (var date: DateAnay); 

Procedure SetOateTlme (date: DateAnay); 

Procedure OateToTime (date: DateAnay; var time: Seconds); 

The current date and time are available as a set of 16-bit integers which 
represent the year, day, hour, minute and second, by calling DateTlme and 
SetOateTime. The date and time are based on the hardware clock/calendar. 
This restricts dates to the years 1980-1995. The clock/calendar continues to 
operate during soft power off, and for brief periods on battery backup if the 
machine is unplugged. If the clock/calendar hasn't been set since the last loss 
of battery power, the date and time will be midnight prior to January 1, 1980. 
Setting the date and time also sets the time stamp described below. 
DateToTime converts a date and time to a time stanp, defined in the next 
section. 

F.9 Time Stamp 

Function TlmeStamp: Seconds; 

Procedure SetTimeStamp (time: Secands]^ 

Procedure TlmeToDate (time: Seconds; var date: OateArray); 

The current date and time are also available as a 32-bit unsigned integer 
which represents the number of secoreis since tt« midni0it prior to 1 JsHiuary 
1901, txy calling TimeStamp and SetTimeStampi The time stamp will roll over 
once every 135 years. Beware— for dates beyond the mid 1960's, the sign bit 
is set. The time stamp is based m the hardware clock/calerKiar. This clock 
continues to operate during soft power off, and for brief periods on battery 
backup if the machine is unplugged. If the clock/calendar hasn't been set 
since the last loss of battery power, the date and time will be midnight prior 
to January 1, 198a Setting the time stamp also sets the date and time 
described alrave. Since the date arid time is restricted to 1980-1995, the time 
stamp is also restricted to this range. TlmeToDate converts a time stamp to 
the date »Td time format defined atoove. 
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F.IO Interface of trie Hardware Uhit 

Unit Hard»»ar8; 
Interface 



type 



Pixels 

MsnyPixels 

CursorHeight 

CursorPtr 

OateArray 



Frames 

Seconds 

Milliseconds 

Microseconds 

SpeakerVolume 

ScreenContrast 

KeybdQIndex 

Keybdid 

Keycap 

KeyCapSet 

KeyEvent 



{ Mouse } 



= Integer; 
= Longint; 
* Integer; 
= "Integer; 
= Record 

year: Integer; 

day: Integer; 

hour: Integer; 

minute: Integer; 

second: Integer; 

end; 
« Longint; 
= Longint; 
= Lorw|Int; 
= Longint; 
« Integer; 
= Integer; 
= 1..1000; 
= Integer; 
« 0-.127; 
= Set Of Keycap; 
= Packed Record 

key: Keycap; 

ascii: Char; 

state: Integer; 

mouseX: Pixels; 

mousey : Pixels; 

time: HilliSeconds; 

end; 



Procedure MouseLocation (var x: Pixels; var y: Pixels); 
PrcKJedure Mtxisel^MJates (ctelay: Milliseconds); 
Procedure MouseScaling (scale: Boolean); 
Procedure MouseThresh (threshold: Pi)«ls); 
Function MouseOdometer: ManyPixels; 
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{ Cursor } 

Procedure CursorLocation (x: Pixels; y: Pixels); 
Procedure Cursor Tracking (track: Boolean); 
Procedure Cursor Image (hotX: Pixels; hotY: Pixels; height: 
DiTsorHeight; data: CursorPtr; mask: CursorPtr); 

Procjedure Busylmage (hotX: Pixels; hotY: Pixels; height: 

iDursorHeight; data: CursorPtr; mask: CursorPtr); 
Procedure BusyOelay (delay: HilliSeconds); 



{ Screen } 

Function FrameCounter: Frames; 

Procedure ScreenSize (var x: Pixels; var y: Pixels); 

FiTJotion Contrast: ScreenContrast; 

Procedure SetContrast (contrast: ScreenContrast); 

Praijedure RampContrast (contrast: ScreertDontrast); 

Function DimContrast: ScreenContrast; 

Procjedure SetDimContrast (contrast: ScreenContrast); 

Fmction FadeOelay: MilliSecorxIs; 
Proc'edure SetFadeOelay (delay: Milliseconds); 

{ Speatfcer } 

FuncJtion Volume: ^3eari<erVolume; 

Procedure SetVolume (volume: SpeakerVolume); 

Procedure Noise (iraweLength: Microseconds); 

Procedure Silence; 

Procedure teep (wavelength: Microseconds; duration: Milliseconds); 
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{ Keytxjard } 

Function KeytJoard: Keybdid; 

Fmction Legends: Keybdid; 

Procedure SetLegends (id: Keybdid); 

Function KeylsOown (key: KeyCap): Boolean; 

Procedure KeyHap (var keys: KeyCapSet); 

Function KeybdPeek (repeats: Boolean; index: KeybdQIndex; var 

event: KeyEvent): Boolean; 
Function KeybdEvent (repeats: Boolean; wait: Boolean; var event: 

KeyEvent): Boolean; 
Procedure RepeatRate (var initial: Milliseconds; var subsequent: 

Milliseconds); 
Procedure SetRepeatRate (initial: Milliseconds; subsequent: 

Milliseconds); 



{ Timers } 

Function MicroTimer: MicroSecmds; 
Function Timer: Milliseconds; 



{ Date and Time } 

Procedure OateTime (var date: OateArray); 

Procedure SetDateTime (date: DateArray); 

Procedure DateToTime (date: DateArray; var time: SecorKJs); 



{ Time Stanp } 

Function TimeStamp: Seconds; 

Procedure SetTimeStainD (time: Seconds); 

Procedure TimeToDate (time: Seconds; var date: DateArray); 
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Lisa Character Set 



NUL 



OLE 



SP 







@ 



SOH 



OCl 



A 



Q 



a 



q 



STK 



DC2 



B 



R 



b 



ETX 
Enter 



DC5 



EOT 



DC4 



$ 



D 



d 



ENO 



NAK 



% 



E 



U 



u 



MK 



SW 



& 



6 



BEL 



ETB 



G 



W 



w 



BS 



CAN 



8 



H 



X 



h 



X 



HT 



En 



9 



y 



LF 



SUB 



Z 



VT 



ESC 
Clear 



K 



FF 



FS 



\ 



D 



CR 



GS 



M 



m 



so 






N 



n 



SI 



H] 



/ 











DEL 



The first 32 characters and CEL are nonprinting control codes. 
The shaded area Is reserved for future use. 
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Error Messages 



Kl Lexical Eirois H-1 

K2 Syntactic Enors H-1 

H3 Semantic Enors K-2 

HA Conditional CompUation H-H 

K5 Compiler Specific Limitations I-Hl 

K6 I/OEtiots H-4 

K7 Clascal Erron H-4 

K8 Code Generation Errors H-5 

K9 Verification Erron H-5 
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HI Le}dcal Emm 

10 Too Hiar»y digits 

11 Digit expected after ' . ' in real 

12 Integer overflow 

13 Digit expected in exponent 

14 End of line encountered in string constant 

15 Illegal character in irput 

16 Premature erKl of file in source progran 

17 Extra characters encountered after end of program 

18 End of file encountered in a ccwment 

H2 Syntactic Enors 

20 Illegal symbol 

Error in simple type 
Error in declaration part 
Error in parameter list 
Error in constant 
Error in type 
Error in field list 
Error in factor 
Error in variable 
Identifier expected 
Integer expected 



21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
46 



(• expected 
)* expected 
[' e)qDected 
]• expected 
: ' e^qaected 
;• exjaected 
-• expected 
, • expected 
*• ex|3ected 

I — 6)^j6Cv6d 

program' expected 

of expected 

begin' expected 

end' expected 

then' expected 

until' expected 

do' expected 

to' or 'downto* expected 
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49 
50 
51 
52 
53 
54 
55 



file" expected 
if expected 
.* expected 

implementation' expected 
interface' expected 
intrinsic' e>pected 
shared' expected 



H3 Semantic Enon 

100 Identifier declared twice 

101 Identifier not of t^e appropriate class 

102 Identifier not declared 

103 Sign not allowed 

104 Number e)q3ected 

105 Lower bouTKl exceeds upper bound 

106 Incompatible subrange types 

107 Type of constant must be integer 

108 Tyf« must not be real 

109 T^f ield must be scalar or subrange 

110 Type incompatible with with tagf ield type 

111 Index type must not be real 

112 iTClex type must be scalar or subrange 

113 Index t3^ must mt be integer or longint 

114 Unsatisfied forward refereixe 

115 Forward reference type identifier cannot appear in variable 

declaration 

116 Forward declaration - repetition of parameter list not allowed 

117 Forward declared function - repetition of result type not allowed 

118 Fmction result type must be scalar, subrange, or pointer 

119 File value parameter not allowed 

120 Missing result type in ftJiction declaration 

121 F -format for real only 

122 Error in type of standard function parameter 

123 Error in tyjie of standard procedure parameter 

124 Number of parameters does not agree with declaration 

126 Result type of parameteric fmction does not agree with 

declaration 

127 Expression is not of set type 

128 Only tests on equality allowed 

129 Strict inclusion not allowed 

130 File comparison not allowed 

131 Illegal type of q3erand(s) 

132 Type of operand must be boolean 

133 Set element type must be scalar or subrange 

134 Set element types rmt compatible 

135 Type of variable is not array or string 

136 Index type is not compatible with declaration 
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137 Type of variable is not record 

138 Type of variable must be file or pointer 

139 Illegal type of loop control variable 

140 Illegal tyjDe of expression 

141 Assignment of files not allowed 

142 Label type incompatible with selecting expression 

143 Subrange bounds must be scalar 

144 Type conflict of operands 

145 Assignment to standard function is not allowed 

146 Assignment to formal function is not allowed 

147 No such field in this record 

148 Type error in read 

149 Actual parameter must be a variable 

150 Multidef ined case label 

151 Missing corresponding variant declaration 

152 Real or string tagf ields not allowed 

153 Previous declaration was not forward 

154 Substitution of stmdard procedure or function is not allowed 

155 riultidefined label 

156 Multideclared label 

157 Undefined label 

158 Undeclared label 

159 Value parameter expected 

160 l^ltidefined record variant 

161 File not allowed here 

162 Unknown compiler directive (not 'external' or 'forward') 

163 Variable cannot be packed field 

164 Set of real is not allowed 

165 Fields of packed records cannot be var parameters 

166 Case selector expression must be scalar or sttorange 

167 String sizes must be equal 

168 Strir^ too loig 

169 Value out of range 

170 Address of standard procedure carMTOt be t^en 

171 Assignment to function result must be done inside function 

172 Loop oxitrol variable must be local 

173 Label value must be in 0..9999 

174 Must exit to an enclosing procedure 

175 Procedure or function has already been declared once 

176 Missing procedure or furrction body 
190 No such unit in this file 
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HL4 Conctttional Compilation 

260 New compile-time variable must be declared at global level 

261 Undefined compile-time variable 

262 Error in compile- time expression 

263 Conditional compilation options nested too deeply 

264 Unmatched ELSEC 

265 Unmatched ENDC 

266 Error in SETC 

267 Unterminated conditional compilation option 

HS Compiler Specific Limitations 

300 Too many nested record scopes 

301 Set limits out of range 

302 String limits out of range 

303 Too many nested procedures/functions 

304 Too many nested include/uses files 

305 Includes not allo«»ed in interface section 

306 Pack and unpack are not implemented 

307 Too many units 

308 Set constant out of range 

309 Structure too large ( > 32K ) 

310 Parameter list too large ( >= 32K ) 

350 Proceckire too large 

351 File name in option too long 

HL6 l/OErron 

400 Not enough room for code file 

401 Error in rereading code file 

402 Error in reopening text file 

403 Unable to open uses file 

404 Error in reading uses file 

405 Error in opening include file 

406 Eror in rereading previously read text block 

407 Not enough room for I-code file 

408 Error in writing code file 

409 Error in reading I-code file 

410 l^TiSble to Ofsn listing file 
420 I/O error on debug file 

K7 Clascal Emnrs 

800 OF missing 

801 Superclass identifier missing 

802 Method NEW is not declared 

803 Subclass declaration not allots Nsre 

804 hetfrod is not a procedure 

805 Method is not imi3lemented 

806 Class is not implemented 

807 Superclass identifier is rwt a class 

808 Ictentifier is not a class 
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809 'hEIH' not allowed here 

810 'NEW »»as expected here 

811 Illegal 'NEW method 

812 Illegal use of class Identifier 

813 Unsafe use of a handle in an assignment statement 

814 Unsafe use of a handle in a WITH statement 

815 Unsafe use of a handle as a var parameter 

HL8 Code Qeneration Enon 

1000-1999 Internal code generation errors 

2000 End of I -code file not found 

2001 Expression too complicated, cede ^nerator ran out of registers 

2002 Code generator tried to free a register that was already free 
2003-2005 Error in ger«rating address 

2006-2010 Error in expressions 

2011 Too maiy globals 

2012 Too many locals 

K9 V^erification Errors 

4000 Bad verification block format 

4001 Source cocte version conflict 

4002 Compiler version conflict 

4003 Linker version conflict 

4100 Version in file less than minimum version supported by program 

4101 Version in file greater than maximum version supported by program 
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Pascal Workshop Files 



This appendix lists the files on the Pascal 1.0 diskettes. 



File Name 


Pascal 


Notes 


Description 


Diskette 






Assefnbler.obj 


2 




Workshop program. 


BYE. TEXT 


1 




Workshop Installation exec file, 


ByteDiff.obj 


3 




utility program. 


Changeseg.oDj 


2 




Utility program. 


Cistart.text 


1 




Workshop installation exec file 


CISTARTl.TEXT 


1 




Worksho|3 installation exec file 


Code.oDj 


2 




Workshop program. 


codeslze.oDj 


2 




Utility program. 


Diff.odJ 


3 




utility program. 


DumpoDj.oDJ 


2 




Utility program. 


DumpPatch.obj 


3 




utility program. 


EDIT. MENUS. TEXT 


3 




Editor support file. 


Editor. Ob j 


3 




Workshop program. 


Filediv.obj 


3 




Utility program. 


File join. Ob j 


3 




utility program. 


flnd.obj 


3 




Utility program. 


FMDATA 




1.2 


Data segment. 


font.heur 




1.2.3 


Data needed to support SYSlLib. 


FONT.HEUR 






Second copy of same file. 


font. lib 




1.2.3 


Data needed to support SYSlLib. 


GETPROFILELOC.TEXT 






Workshop installation exec file 


GETYESNO.TEXT 






Workshop Installation exec file 


Gxref.obJ 






utility program. 


INSERTDISK.TEXT 






Workshop Installation exec file 


Intrinsic. lib 




2.3 


Library directory. 


lOSFplib.obj 






Library unit w/interface. 


lOSPaslib.obj 




2.3 


Library unit w/interface. 


LDSPREFERENCES.OBO 


3 




Workshop program. 



Note 1: These files are identical to Office system Release 1.0 files. 

Note 2: These files are identical to Office System Release 1.2 files. Office System 
1.2 is functionally identical to Office System 1.0. but is released to ensure 
compatibility with Pascal 1.0, BASIC-Plus 1.0. and COBOL 1.0. 

Note 3: These files are the minimum necessary to run a user program in the 

Workshop environment A user program may require other flies as well. 
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File Name 


Pascal 


Notes Description 


Diskette 




LDS_RES_PROCS,TEXT 


3 


Workshop data. 


Linker. Ob j 


2 


Workshop program. 


N68k.err 


2 


Assembler data. 


N68K. opcodes 


2 


Assembler data. 


Objiollb.obj 


2 


Library unit (no interface). 


OSERRS.ERR 


1 


3 Workshop data. 


PAPER. TEXT 


3 


Workshop data. 


Pascal. Ob j 


2 


WorkshoJ3 program. 


PASERRS.ERR 


2 


Workshop data. 


PASLIBCALL.OBJ 


2 


Library unit w/interface. 


Portconfig.obj 


3 


Utility program. - — 


QD/BOXES.OBJ 


2 


Quickdraw sample progran. 


QD/BOXES.TEXT 


2 


Quickdraw satifjle program. 


QD/FM68K.0BJ 


2 


QuickDraw unit (no interface) 


QD/F0NTM6R.0BJ 


2 


QuickDraw unit w/interface. 


Q0/GRAF30.0BJ 


2 


QuickDraw unit w/interface. 


QD/GRAFLIB=OBJ 


2 


QuickDraw unit (no interface) 


Q0/6RAFTYPES.TEXT 


2 


Quickdraw assembly interfaces 


Q0/6RAFUTIL.08J 


2 


QuickDraw unit w/interface. 


QD/HARDWARE.OBJ 


2 


Hardware unit w/interface. 


QD/HWINTL.OBJ 


2 


Hardware unit (no interface). 


QD/M/BOXES.TEXT 


2 


Exec file. 


QD/M/QDSAMPLE.TEXT 


2 


Exec file. 


QD/QDSAMPLE.OBJ 


2 


Quickdraw sample program. 


QD/QOSAHPLE.TEXT 


2 


Quickdraw saiiple program. 


QO/QDSTUFF.TEXT 


2 


Quickdraw unit filenames. 


QD/QOSUPPORT.OBJ 


2 


QuickDraw unit w/interface. 


QD/QUICKDRAW.OBJ 


2 


QuickDraw unit w/interface. 


Q0/ST0RA6E.0BJ 


2 


QuickDraw unit w/interface. 


QD/UNIT68K.0BJ 


2 


(^jickDraw unit (no interface) 


QD/UNITHZ.OBJ 


2 


QuickDraw unit w/interface. 


QO/UNITSTD.OBJ 


2 


QuickDraw unit w/interface. 


resident chsnnel 


1 


1^2,3 System data. 


Segnep.obj 




Utility program. 


Shell. workshop 


1 


5 workshop main program. 


Sulib.obj 


1 


3 Library unit w/interface. 


Sxref.obj 


3 


Utility program. 



Note 1: These files are identical to Office System Release 1.0 files. 

Note 2: These files are identical to Office System Release 1.2 files. Office System 
1.2 is functionally identical to Office System 1.0, but is released to ensure 
compatibility with Pascal 1.0, BASIC-Plus 1.0, and COBOL 1.0. 

Note 3: These files are the minimum necessary to run a user program in M^ 

Workshop environment A user program may require other files as well. 
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File Name 


Pascal 


Notes 


Description 


Diskette 






SXREF.OhlT.TEXT 


5 




Data. 


Sysilib.obj 


1 


1,2,3 


Library units (no interface). 


SYS2LIB.0BJ 


3 


1,2,3 


Library units (no interface). 


SYSCALL.OBJ 


2 




Library tnit w/ interface. 


SYSTEM. BT PROF 




1,2,3 


System support. 


SYSTEM. BT TWIG 




1,2,3 


System sujajxjrt. 


SYSTEM. DEOJG 






Workshop progrEun. 


SYSTEM. DEBUG2 






Workshop program. 


SYSTEM. lUDIRECTORY 




1,2,3 


System data. 


SYSTEM. LLD 




1,2,3 


System program. 


SYSTEM.LOG 




1,2,3 


System data. 


SYSTEM. OS 




2,3 


System program. 


System. Shell 




1,2,3 


System program. 


SYSTEM.STACKl 




1,2,3 


System data. 


SYSTEM. STACK2 




1,2,3 


System data. 


SYSTEM. STACK3 




1,2,3 


System data. 


SYSTEM. STACK4 




1,2,3 


System data. 


SYSTEM. SYSLOCl 




1,2,3 


System data. 


SYSTEM. SYSL0C2 




1,2,3 


System data. 


SYSTEM. SYSL0C3 




1,2,3 


System data. 


SYSTEM. SYSL0C4 




1,2,3 


System data. 


SYSTEM. TIMER PIPE 




1,2,3 


System data. 


SYSTEM. UNPACK 




1,2,3 


System data. 


term. menus. text 


3 




Data for transfer program. 


transfer. Ob j 


3 




Workstwp program. 


Uxref.obj 


3 




Utility program. 


UXREF.UMAP.TEXT 


3 




Data for UXREF program. 


WMDATA 


1 


1,2 


Data segment. 


Xejectem.obj 


1 




Workshop installatim program 


{T11}BUTT0NS 


3 


2 


Data. 


{T11}MENUS.TEXT 


3 


2 


Data. 



Note 1: These files are identical to Office System Release l.O files. 

Note 2: These files are identical to Office System Release 1.2 files. Office System 
1.2 is functionally identical to Office System 1.0, but is released to ensure 
compatibility with Pascal 1.0, BASIC-Plus 1.0, and COBOL l.a 

Note 3: Tliese files are the minimum necessary to run a user program in Vn& 

Woikshc^ environment A user progrsm may require other files as well. 
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Please note that tHe topic references In this Index are by section number. 



abs function 11.4.2 
acicuracy in real arithmetic D 
actual-parameter 5.2, 7.1, 7.3 

syntax 5.2 
actual -parameter-list 5.2 

syntax 5.2 
actual-parameters in procedure call 

6.1.2 
AddPt procedure E.9.17 
anomalies in Lisa Pascal B 
Apple II Pascal A 
Apple III Pascal A 
applestuff unit A 
arcs, graphic operations E.9.10 
arctan function 11.4.9 
arithmetic functions 11.4 
arithnnetic operators 5.1.2, D 
array 3.2.1, 4.3.1 

conponent 3.2.1, 4.3.1 

reference 4.3.1 
array-type 3.2.1 

syntax 3.2.1 
ascent line E.5.2 
ASCII 3.1.1.5 

assembly language, (^ickDraw E.ll 
assignment-compatibi 1 i ty 3.4.3 
assignment-statement 6.1.1 

syntax 6.1.1 



-B- 



BackColor procedure E.9.5 
BackPat procedure E.9.1 



base line E.5.2 
base-type 3.2.3, 3.3, 5.3 

of pointer-type 3.3 

syntax 3.3 

scope anomaly B 

of set-type 3.2.3, 5.3 
Beep procedure F.4 
bit image E.4.1 
bit transfer operations E.9.13 
Bitttap data type E.4.2 
bitmaps E.4.2 

bitwise txx3lean operations A 
blank character 1.1 
blank segment 8.3, 9.1 
block 2 

syntax 2.1 
block-structured I/O 3.2.4, 

10.1.1-2, 10.4 
blockread function 3.2.4, 10.4.1 
blockwrite function 3.2.4, 10.4.2 
boolean 3.1.1.4, 5.1.3, 5.1.5.2, 
10.3.3.7, 12.3-12.4 

ctMiparisons 5.1.5.2 

constants as control values 12.3, 
12.4 

operands, evaluation of 5.1.3 

operators 5.1.3 

data type 3.1.1.4 

values in text-oriented output 
10.3.3.7 
boundry rectangle E.4.2 
Boxes program E.14.2 
buffer variable 10.1.3, 10.1.7 
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Index 



t)uilt-in procedures & functions 10, 

11 
busy cursor F.2.2 
BusyDelay procedure F.2.2 
Busylmage procedure F.2.2 
byte array 11.7 
byte-oriented procedures & functions 

11.7 
byte-size files 3.2.4 
bytestream type A 



camera eye E.12 
case 6.2.2.2 

syntax 6.2.2.2 
case-constant in case statement 

6.2.2.2 
case-sensitivity 1.1, 1.2, \.k 
case-statement 6.2.2.2 

efficiency 12.5 

syntax 6.2.2.2 
char 1.6.1, 3.1.1.5, 10.3.1.1, 
10.3.3.2, 11.5 

constant 1.6.1 

type 3.1.1.5 

values in text-oriented I/O 
10.3.1.1, 10.3.3.2 
character l.l, 3.2.4, 4.3.1 

device 3.2.4. 10.1.1-2 

files 3.2.4 

font E.5.2 

in string 4.3.1 

set 1.1 
character style E.5.2 
CharWidth function E.9.4 
chr function 11.5.2 
Clip30 function E.12. 4 
ClipRect procedure E.9.1 
clipRgn E.5 



clock/calendar F.8, F.9 
close procedure 10.1.5 
ClosePicture procedure E.9.14 
ClosePoly procedure E.9.15 
ClosePort procedure E.9.1 
CloseRgn procedure E.9.11 
closing a file 10.1.5 
code generation 12.1 
color drawing E.7.2 

routines E.9.5 
ColorBit procedure E.9.5 
comment 1.8 
conparisons 5.1.5 
compatibility of parameter lists 

7.3.5 
compatible types 5.4 
cof?pile-timg expressions & variables 

12.2.1-3 
compiler 1.8, 12, A 

commands 1.8, 12.1-2, A 
component of array 3.2.1, 4.3.1 
conpcMTent of file 3.2.4, 4.3.3 
component-type of array 3.2.1 
component-type of file 3.2.4 
conpound-statement 6.2.1 

syntax 6.2.1 
concat function 11.6.3 
conditional compilation 12.2 
conditional-statement 6.2,2 

syntax 6.2.2 
constant 1.4-7 

syntax 1.7 
constant-declaration 1.7, 2.1, B 

scqse anomaly 6 

syntax 1.7 
constant-declaration-part 2 . 1 

syntax 2.1 
constants, assembly language E.11.1 
contrast control F.3.1 
Contrast function F.3.1 
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control -variable 6.2.3.3 

syntax 6.2.3.3 
coordinate plane E.3.1 
coordinates, grafPort E.3.1, E-6 
copy function 11.6.4 
CopyBits procedure E.9.13 
CopyRgri procedure E.9.11 
cos function 11.4.5 
CR character l.l, 1.6, 10.3 

in text-oriented I/O 10.3 
crmch 10.1.5 
current block number 10.4 
current file position 4.3.3 
cursor control 10.3.7, F.2 
Cursor data type E.4.4 
cursor-handling routines E.9.2 
CursorHeight data type F.io 
Cursorlmage procedure F.2 
CursorLocation procedire F.2.1 
CursorPtr data type F.IO 
cursors, QuickDraw E.4.4 
Cursor Tracking procedure F.2.1 
customizing QuickDraw operations 

E.IO 
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data bitmap F.2 
data types 3 
assembly language E.11.2 
Graf 30 E.12.3, E.13.5 
QuickDraw E.2.2, E.13.2 
datafile 10.1.2 
date F.8, F.9 
DateArray data type F.IO 
DateTime procedure F.8 
DateToTlme procedure F.8 
desd key diacritical s F.5.4 
d^xigging 12.1 



defining declaration 7.1 
delete procedure 11.6.5 
descent line E.5.2 
device 10.1.1-2 

character 10.1.1, 10.1.2 

file-structured 10.1.1, 10.1.2 

types 10.1.1, 10.1.2 
diacritical marks F.5.4 
DiffRgn procedure E.9.11 
digit 1.1 
digit-sequence 1.4 

syntax 1.4 
DimDontrast function F.3.2 
dimensions of Lisa screen E.4.1 
directive 1.3 

diskette insertion switches F.5 
display screen F.3 
DisposeRgn procedure E.9.11 
div operator A 
division by zero (real arithmetic) 

3.1.1.3, 
OLE Character 10.3 
DrawChar proceckure E.9.4 
drawing E.7 

color E.7.2 
DrawPlcture procedure E.9.14 
Drawstring procedure E.9.4 
DrawText procedure E.9.4 
dynamic allocation procedures 11.2 



efficiency, case-statements 12.5 
empty set 5.3 
EraptyRect function E.9.6 
EraptyRgn function E.9.11 
enumer ated-type 3.1.2 
syntax 3.1.2 
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eof function 10.1.7 

and varicftjs procedures 10.1.3-4^ 
10.1.7, 10.2.1-2, 10.2.4, 
10.3.1-2, 10.4.1 
eoln function 10.3.5 

and read and readln procechjres 
10.3.1, 10.3.2 
EqualPt function E.9.17 
EqualRect function E.9.6 
EqualRgn function E-9.11 
EraseArc procedure E.9.10 
EraseOval procedure E.9.8 
ErasePoly proceckjre E.9.16 
EraseRect procedure E.9.17 
EraseRgn procedure E.9.12 
EraseRoundRect procedure E.9.9 
ETX character A 
exit procecKjre 11.1.1, A 
exp function 11.4.6 
expression 5 

syntax 5 
extended coipparisons A 
external file 10.1 
external function 7.2 
external procedure 7.1-2 



factor 5 
svntsY S 

-J - • 

FadeDelay function F.3.2 

field of record 3.2.2, 4.3.2, 6.2.4 

field-declaration 3.2.2 

syntax 3.2.2 
field-designator 4.3.2 

syntax 4.3.2 
field-list 3.2.2 

syntax 3.2.2 



file 3.2.4, 4.3.3, 10 

buffer 4.3.3 

buffer and eof functim 10.1.7 

buffer arid reset procechjre 10.1.3 

conponent 3.2.4, 4.3.3 

identifier as parameter type 7.3 

of char 3.2.4 

position and reset procedure 
10.1.3 

record 10.2 

reference 4.3.3 

species 10.1.2 

standard file-type identifier 
3.2.4, 10.1, 10.4 

types and reset procedure 10.1.3 

vari^le 5.2.4, 4.5.3, 10 
file-buffer-synt)ol 4.3.3 

syntax 4.3.3 
file-structured device 3.2.4, 

10.1.1-2, 10.4 
file-type 3.2.4 

syntax 3.2.4 
FillArc procedure E.9.10 
fillchar procechjre 11.8.3 
FillOval procedure E.9.8 
FillPoly procedure E.9-16 
FillRect procedure E.9.7 
FillRgn prtxiedure E.9.12 
FillRoundRect procedure E.9.9 
final -value 6,23.3 

syntax 6.2.3.3 
finite real values 3.1.1.3 
fixed-part 3.2.2 

syntax 3.2.2 
fixed-point output of real value 

10.3.3.4 
floating-point arithmetic D 
floating-point output of real value 

10.3.3.4, A 



Index-4 



Pascal Reference h'ianual 



Index 



font numbers E.15 
fonts E.5.2 
for-statement 6.2.3.3 

syntax 6.2.3.3 
Fordiolor procechjre E.9.5 
foreign characters F.5.4 
formal-parameter-list 7.3 

syntax 7.3 
formal-parameters and procechjre call 

6.1.2 
forward declaration 7.1-2 
FrameArc procechjre E.9.10 
FrameCoLffiter function F.3 
FrameOval procedure E.9.8 
FramePoly procedure E.9.16 
FrameRect procedure E.9.7 
FrameRgn procedure E.9.12 
FrameRomcHRect procedure E.9.9 
Frames data type F.IO 
function 7.2-3 
function-body 7 .2 

syntax 7.2 
function-call 5, 5.2, 7.2, 7.3 

syntax: 5.2 
ftnct ion-declaration 7.2 

syntax 7.2 
function-heading 7 . 2 

syntax 7.2 
functional paraneter 7.3.4 
functions, assembly language E.11.4 



get procedure 10.2.1, 10.2.3 
GetClip procedure E.9.1 
GetFontlnfo procedure E.9.4 
GetPen procechjre E.9.3 
GetPenState procedure E.9.3 
GetPixel function E.9.18 
GetPort procedure E.9.1 



6etPort30 procedure E.12.4 
global coordinates E.6, E.9.17 
global variables, assenoiy language 

E.11.3 
GlobalToLccal procalire E.9.17 
goto-statement 6.2, A 

syntax 6.1.3 
gotoxy procedure 10.3.7.2 
Graf 30 E.12 

data types E.12. 3, E.13.5 

sample program E.14.2 
Graf Device procedure E.9.1 
grafPort coordinates E.3.1, E.6 
Graf Port data type E.5 
grafPort routines E.9.1 
graf Ports E.5 
GrafPtr data type E.5 
Graf Verb data type E.IO 
graphics pen E.5.1 
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halt procedure 11.1.2, A 
handles E.3.4 

picture E.8.1 

polygon E.8.2 

region E.3.4 
hardware interface F 
heap 11.2 

heapresult function 11.2.2 
hex-digit l.l 
hex-digit-sequence 1 . 4 

syntax 1.4 
hexadecimal constants 1.4 
HideCursor procedure E.9.2 
HidePen procedure E.9.3 
host program or unit 9 
host-type of subrange 3.1.3 
hotspot E.4.4, F.2 
hourglass cursor F.2. 2 
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identical types 3. A 
identifier 1.2 

of program 8.1 

syntax 1.2 
identifier-list 3.1.2 

syntax 3.1.2 
Identity procedure E. 12.4.2 
IEEE Floating-Point Standard D 
if -statement 6.2.2.1 

qptimization 12.3 

syntax 6.2.2.1 
implementation-part 9.1.1 

syntax 9.1.1 
in operator 5.1.5.5 
index 4.3.1 

in variable-reference 4.3,1 

syntax 4.3.1 
index- type 3.2.1 

syntax 3.2.1 
infinities 3.1.1.3, D 
InitCursor procedure E.9.2 
InitGraf procedure E.9.1 
initial-value 6.2.3.3 

syntax 6.2.3.3 
initialization-part A 
InitPort procedure E.9.1 
input (standard file) 10.1.7, 10.3 
input file control (in compilation) 

12.1 
input variables in read procedure 

10.3.1 
input/output 10 
insert procedure 11.6.6 



InsetRect procedure E.9.6 
InsetRgn procedure E.9.11 
integer 1.4, 3.1.1.1-2, 10.3.1.2, 
10.3-3.3, 11.3-5, D 

arithmetic 3.1.1.1, 3.1.1.2 

constant 1.4 

conversion overflow D 

data type 3.1.1.1, 3.1.1.2 

data type conversions 3.1, 
3.1.1.5, 3.1.2, 11.5.1 

values in text-oriented I/O 
10.3.1.2, 10.3.3.3 
interactive file- type A 
interface-part 9.1.1 

syntax 9.1.1 
intrinsic-^mit 9.2 
INTRINSIC. LIB 9.2, 12.1 
invalid operations in real arithmetic 

D 
InvertArc procedure E.9.10 
InvertOval procedure E.9.8 
InvertPoly procedure E.9.16 
InvertRect procedure E.9.7 
InvertRgn procedure E.9.12 
InvertRtxincKect procedure E.9.9 
ioresult function 10.1.2, 10.1.6 



key state F.5.3 
KeybdEvent f met ion F.5.3 
KeybdId data type F.IO 
KeybdPeek function F.5.3 
KeybdOIndex data type F.IO 
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keyboard 3.2.4^ 10.1.1, 10.3, 
10.3.7.1, F.5 

attributes F.5.1 

echoing on input 10.3 

events F.5, F.5. 3 

identification F.5.1 

layouts F.5.1 

legends F.5.1 

physical 3.2,4, 10.1.1, 10.3, 
10.3.7.1 

queue F.5. 3 

repeats F.5. 5 

state F.5. 2 

testir^ 10.3.7.1 
Keyboard furrction F.5.1 
Keycap data type F.IO 
KeyCapSet data type F.io 
keycodes F.5 
KeyEvent data type F.IO 
KeylsOown function F.5. 2 
KeyHap procedure F.5. 2 
keypress function 10.3.7.1 
KillPicture procedure E.9.14 
KillPoly procedure E.9.15 



label 1.5, 2.1, 6 

on statement 6 

syntax 2.1, 6 
label -declaration-part 2.1 

syntax 2.1 
Legends function F,5.1 
length attribute 3.1.1.6 
length function 11.6.1 
letter 1 . 1 
Line procedure E.9.3 
line-drawing routines E.9.3 
Line20 procedure E.12.4 
Line3D procedure E.12.4 



LineTo procedure E.9.3 
LineTo20 procedure E.12.4 
LineTo30 procedure E.12.4 
Linker 7.1 
listing control 12.1 
In function 11.4.7 
local coordinates E.6, E.9.17 
LocalToGlobal procedure E.9.17 
lock 10.1.5 

long inte^r data type A 
longint 1.4, 3.1.1.2, 10.3.1.2, 
10.3.3.3, 11.3-5, D 
arithmetic 3.1.1.2 
constant 1.4, 1.6, 1.7 

11.3.4 
data type 3.1.1.2 
data type conversions 11.3.3, 
values in text-oriented I/O 
10.3.3.3 
LookAt procedure E. 12.4.1 
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ManyPixels data type F.IO 
MapPoly procedure E.9.18 
MapPt procedure E.9.18 
MapRect procedure E.9.18 
MajjRgn procedure E.9.18 
mark procedure 11.2.3, A 
mask bitmap F.2 
maxint 3.1.1.1 
memavail function 11.2.5 
member-group 5.3 

syntax 5.3 
memory allocation procedures 11.2 
microsecond timer F.6 
Microseconds data type F.IO 
MicroTimer function F.6 
millisecoTd timer F.7 
Milliseconds data type F.IO 
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missing syntjol E.5.2 
rood operator A 
RKxrse F.l 

button F.5 

plug F.5 
HouseLocation procechjre F.l.l 
MouseOdometer procedure F.l. 4 
HouseScaling procedure F.l. 3 
houseThresh procedure F.l. 3 
MouseUpdates procedure F.l. 2 
Move procedure E.9.3 
Move20 procedure E.12.4 
Move3D procedure E.12.4 
moveleft procedure 11.7.1 
HovePortTo procedure E.9.1 
mover i|^t procedure 11. 7. 2 
HoveTo procedure E.9.3 
MoveTo2D procedure E.12,4 
MoveTo3D procedure E.12.4 
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NaNs 3.1.1.3, 

new procedure 3.3, 11.2.1, A 

NewRgn function E.9.11 

nil 3.3, 4.3.4, 11.2.1 

Noise procedure F.4 

normal 10.1.5 

nufitoer 1.4 

numerical comDarisons 5.1.5.1 



object file 9 
ctoject of ixjinter 4.3.4 
ObscureCursor procedure E.9.2 
odd function 11.4.1 
OffsetPoly procedure E.9.15 
OffsetRect procedure E-9.6 
OffsetRgn procedure E.9.11 



0pen30Port procedure E.12.4 
opening a file 10.1, 10.1.2-4 
OpenPicture function E.9.14 
OpenPoly function E.9.15 
OpenPort procedure E.9.1 
(^penRgn proceckjre E.9.11 
operands 5 

compile-time 12.2.3 

in expressions 5 
curators 5 

compile-time 12.2.3 

in expressions 5 
optimization of if, repeat, and while 

statements 12.3, 12.4 
ord function 3.1, 3.1.1.5, 3.1.2, 

11.5-1 
ord4 function 3.1.1.2, 11.3.3 
order of evaluation of operands 

5.1.1 
ordinal functions 11.5 
ordinal -type 3.1 

and ord function 11.5.1 

and ord4 function 11.3.3 

and pred function 11.5.4 

and succ function 11.5.3 

syntax 3.1 
ordinal-type-identifier 3 
ordinal ity 3.1 
otherwise-clause 6.2.2.2 

syntax 6.2.2.2 
output (standard file) 10.3 
output expression in write procedure 

10.3.3 
output file in write procedure 

10.3.3 
output-specs in write procechjre 

10.3.3 
ovals, graphic operations E.9.8 
overflow (real arithmetic) 

3.1.1.3, D 
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packed array of char 5.1.5.6, 
10.3.1.5, 10.3.3.6, 11.8 
ccmparisons 5.1.5.6 
fillc*iar procedure 11.8.3 
seaming functions 11.8.1, 11.8.2 
text-oriented I/O 10.3.1.5, 
10.3.3.6 

packed data types 3.1.1.6, 3.2 

page procedure 10.3.6 

PaintArc procedure E.9.10 

PaintOval procedure E.9.8 

PaintPoly procedure E.9.16 

PaintRect procedure E.9.7 

PaintRgn procedure E.9.12 

PaintRoundRect procedire E.9.9 

parameter 7.1, 7.3 

parameter list coinpatibility 7.3.5 

parameter -declaration 7.3 
syntax 7.3 

paraneters in proceclire call 6.1.2 

Pascal conpiler 12 

Pattern data type E.4.3 

fi^ttern trmsfer ruocte E.7.1 

patterns E.4.3 

pen E.5.1 

pen routines E.9.3 

PenMode procedure E.9.3 

PenNormal procedure E.9.3 

PenPat procedure E.9.3 

PenSize procedure E.9.3 

performance paialty for longint 
values 3.1.1.2 

PicCorament procedure E.9.14 

PicHandle data type E.8.1 

PicPtr data type E.8.1 

picture ccmments E.8.1 

Picture data type E.8.1 

picture frame E.8.1 

picture routines E.9.14 



pictures E.8.1 

Pitch procedure E. 12.4.2 

pixel E.4.1 

Pixels data type F.IO 

Point data type E.3.2 

pointer 4.3.4, 11.2 

pointer function 3.3, 11.3.4 

pointer-object-symbol 4.3.4 

syntax 4.3.4 
pointer-reference 4.3.4 
pointer-type 3.3 

conversions 11.3.3, 11.3.4 

syntax 3.3 
pointer-type-identifier 3 
points E.3.2 

points, calculations E.9.17 
Polygon data type E.8.2 
polygons £.8.2 

calculations E.9.15 

grqprfiic qperations E.9.16 
Polyf^le data type E.8.2 
PolyPtr data type E-8.2 
portBlts E.5 
portRect E.5 
PortSize procedure E.9.1 
pos function 11.6.2 
power switch F.5 
precedence of qperators 5 
pred fuTOtion 3.1, 11,5.4 
predecessor 3.1 
procedural parameter 7.3.3 
procedire 7.1, 7.3 
procedure-and-function-declaration- 
part 2-1 

syntax 2.1 
procedure-twdy 7.1 

syntax 7 . 1 
procedure-declaration 7 . 1 

syntax 7.1 
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procecfcjre-heading 7 . 1 

syntax 7 . 1 
procedure-statement 6.1.2, 7.1 

syntax 6.1.2 
procedures, assembly language E.11.4 
program 8 

identifier 8.1 

segments 8.3 

syntax 8.1 
program-heading 8 . 1 

syntax 8.1 
program-parameters 8.1, 

syntax 8.1 
Pt2Rect procedure E.9.6 
PtInRect function E.9.6 
PtinRgn function E.9.11 
PtToAngle procedure E.9.6 
purge 10.1.5 
put procedure 10.2.2-3 
pwroften function Ilo4=l0 
pyramid E . 12 



8.2 



ODProcs data type E.IO 
QOProcsPtr data type E.IO 
ODSample program E.2.1, E.14.1 
QDSupfDort unit E.15 
qualifier 4.3 
syntax 4.3 
'^jickDras E 

QuickDraw data types E.2.2, E.13.2 
QuickDraw glossary E.16 



QuickDraw routines E.9 

arcs E.9. 10 

bit transfer E.9. 13 

color drawir^ E.9. 5 

cursor handling E.9. 2 

customizing E.IO 

graf Ports E.9.1 

line drawing E.9. 3 

miscellaneous utilities E.9. 18 

ovals E.9. 8 

pen E.9. 3 

pictures E.9. 14 

points E.9. 17 

polygons E.9. 15, E.9. 16 

rectangles E.9.6, E.9. 7 

regions E.9.11, E.9. 12 

rowTded-corner rectangles E.9. 9 

text drawing E.9. 4 

wedges E.9. 10 
QuickDraw sample programs E.2.1, 

E.14 
QuickDraw summary E.13 
QuickDraw, using from assembly 

language E.U 
quoted-character-constant 1.6.1 

syntax 1.6.1 
quoted-string-constant 1.6 

syntax 1.6 



RanfjOantrast procedure F.3.1 
Random function E.9. 18 
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range-checking 3.1.3, 12.1 
read procedure 10.3.1 
readin procedure 10.3.2 
real 1.4, 3.1.1.3, 10.3.1.3, 
10.3.3.4, 11.3-4, D 

arithmetic 

constant 1.4 

data type 3.1.1.3, 

data type and round function 11.3.2 

values 3.1.1.3 

values arxi write procedure D 

values in text-oriented I/O 
10.3.1.3, 10.3.3.4, D 
real-type 3.1 

syntax 3.1 
real-type-ictentifier 3 
record 3.2.2, 4.3.2 

field 3.2.2, 4.3.2 

number aid seek procedire 10.2.4 

of file 10.2 

reference 4.3.2 

refereixe in with statement 6.2.4 
record-oriented I/O 10.2 
record- type 3.2.2 

new procedure 11.2.1 

syntax 3.2.2 
rectangle calculation routines E.9.6 
Rectangle data type E.3.3 
rectangles E.3.3 

graphic operations E.9.7 
RectlrtRgn function E.9.11 
RectRgn procedure E.9.11 
recur sim 7.1-2 
redeclaration of identifier 2.2.2, 

2.2.4 
Region data type E.3.4 
regions E.3.4 

calculations E.9.11 

graphic qperaticMis E.9.12 
regular-unit 9.1 

syntax 9.1.1 



relational operators 5.1.5 
release procedure 11.2.4, A 
repeat-statement 6.2.3.1 

optimization 12.4 

syntax 6.2.3.1 
repeating keys F-5.5 
RqpeatRate procedure F.5.5 
repetitive-statement 6.2.3 

syntax 6.2.3 
reserved words 1.1 
reset proceckire 10.1, 10.1.5, A 
result-type 7.2 

syntax 7.2 
rewrite procedure 10.1.4 
RgnHarcile data type E.3.4 
RgnPtr data type E.3.4 
Roll procedure E.12.4.2 
rotation E . 12 
romd function 11.3.2, D 
rounded-corner rectangles E.9.9 
rounding in real arithmetic D 
row width E.4.1 



Scale proceckjre E.12.4.2 
scale-factor 1.4 

syntax 1.4 
ScalePt procedure E.9.18 
scan function A 
scaneq function 11.8.1 
scanne function 11.8.2 
scope 2.2 

of standard objects 2.2.5 
screen 10.3, 10.3.7.2, F.3 

contrast F.3.1 

cursor control 10.3.7.2, F.2 

fading F.3. 2 

physical 10.3 
ScreenContrast data type F.IO 
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ScreenSize procedure F.3 
ScrollRect procedure E.9.13 
Seconds data type F.IO 
SectRect function E.9.6 
SectRgn procedure E.9.il 
seek procedure 10.2.3 
segment keyword A 
segmentation 8.3 
segments 8.3, 9.1, 9.2.1 
selector in case statement 6.2.2.2 
set 3.2.3, 5.1.4, 5.1.5.4, 5.3 

cotiparisons 5.1.5.4 

membership testing 5.1.5.5 

operators 5.1.4 

values 5.3 
set-constructor 5, 5.3 

syntax 5.3 
set-type 3.2.3 

syntax 3.2.3 
SetClip procedure E.9.1 
SetContrast procedure F.3.1 
SetCursor procedure E.9.2 
SetDateTime procedure F.8 
SetDimContrast procedure F.3. 2 
SetEmptyRgn procedure E.9.11 
SetFgttteDelay procedure F.3. 2 
SetLegends procedure F.5.1 
SetOrigin procedure E.9.1 
SetPenState procedure E.9.3 
SetPort procedure E.9.1 
SetPort3D procedure E.12.4 
SetPortBits procedure E.9.1 
SetPt procedure E.9.17 
SetPt2D procedure E.12.4 
SetPt3D procedure E.12.4 
SetRect procedure E.9.6 
SetRectRgn procedure E.9.11 
SetRepeatRate procedure F.5.5 
SetStcProcs procedure E.IO 
SetTimeStamp procedure F.9 



SetVolume procedure F.4 
ShowCursor procedure E.9.2 
ShowPen procedure E.9.3 
sign 1.4 

syntax 1.4 
signed zero 3.1.1.3 
signed-nufflber 1.4 

syntax 1.4 
Silence procedure F.4 
sinple-expressicn 5 

syntax 5 
simple- statement 6 . 1 

syntax 6.1 
sinple-type 3 . 1 

syntax 3.1 
si!sple~type~ identifier 3 
sin function 11.4.4 
size-attribute 3.1.1.6 

syntax 3.1.1.6 
sizeof function 11.7.3 
Skew procedure E.12.4. 2 
source transfer mode E,7.1 
SpaceExtra procedure E.9.4 
speaker F.4 

SfDeakervolume data type F.io 
special symbols 1.1 
sqr function 11.4.3 
sqrt function 11.4.8, D 
stack space and memavail function 

11.2.5 
standard procedires md functions 

for I/O 10 

10, 11 
standard simple-types 3.1 
statement 6 

syntax 6.1 
statement-part 2.1 

syntax 2 . 1 
StdArc proceckjre E.IO 
StdBits procedure E.IO 
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StdComment procedure E.IO 
StdGetPic procedure E.IO 
StdLine procedure E.IO 
StdOval procedure E.IO 
StcFoly procedure E.IO 
StcPutPic proceckire E.IO 
StdRect procedure E.IO 
StdRgn procedure E.IO 
StdText procedure E.IO 
StdTxMeas function E.IO 
string 1.6, 3.1.1.6, 4.3.1, 5.1.5.3, 
10.3.1.4, 10.3.3.5, 11.6, A 

character 4.3.1 

cowparisons 5.1.5.3 

concatenation 11.6.3 

constant 1.6, 3.1.1.6 

constant comparisons 5.1.5.3 

length function 11.6.1 

procedires and functions 11.6 

reference 4.3.1 

substring copying 11.6.4 

substring deletion 11.6.5 

substring insertion 11.6.6 

substring search 11.6.2 

values in text-oriented I/O 
10.3.1.4, 10.3.3.5 
string-character 1 . 6 

syntax 1.6 
string- type 3.1.1.6 

syntax 3.1.1.6 
string-type-identifier 3 
StringWidth function E.9.4 
structured- statement 6 . 2 

syntax 6.2 
structured-type 3 . 2 

syntax 3.2 
structured-type -identifier 3 
Stuff Hex procedure E.9.18 
SubPt procedure E.9.17 



subrange-type 3.1.3 

syntax 3.1.3 
succ function 3.1, 11.5.3 
successor 3.1 
syntax di^rans, complete collection 

C 
syntax diagrams, explgareticMn Preface 
system intrinsic library 9.2.2, 12.1 



tag constants in new and dispose 

procedures 11.2.1-2 
tag-field 3.2.2 
tag-field- type 3.2.2 

syntax 3.2.2 
term 5 

syntax 5 
testing set membership 5.1.5.5 
text E.5.2 

text type 3.2.4, 10.1.2, 10.3 
text -drawing routines E.9.4 
text-oriented I/O 10.3 
TextFace procedure E.9.4 
textfile 10.1.2, 10.3, A 
textflle format 10.1.2, 10.3 
TextFont procedure E.9.4 
TextMode procedure E.9.4 
TextSize procedure E.9.4 
TextWidth function E.9.4 
three-dimensional graphics. See 

Graf 3D. 
time F.8, F.9 
time stamp F.9 
Timer function (millisecond timer) 

F.7 
timers F.6, F.7 
TimeStamp function F.9 
TimeToDate proceckire F.9 
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transfer functions 11.3 
transfer modes E.7.1 
Transform procedure E.12.4,2 
transformation matrix E.12 
Translate procedure E. 12.4.2 
treesearch procedure A 
trunc function 11.3.1, K D 
turtlegraphics unit A 
type 3 

compatibility and identity 3.4 

syntax 3 
type-declaration 3 

syntax 3 
type-declaration-part 2.1, 3.5 

syntax 2.1 
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UCSO Pascal A 

unary arithmetic operators 5.1.2 
underscore character A 
UnionRect procedure E.9.6 
UnionRgn procedure E.9.11 
unit 9 

intrinsic 9.2 

regular 9.1 
unit-heading 9.1.1 

syntax 9.1.1 
msigned-cwstant 5 

syntax 5 
unsigned-integer l . 4 

syntax 1.4 
unsigned-number 1 . 4 

syntax 1.4 
unsigned-real 1.4 

syntax 1.4 
untyped file 3.2.4, 10.1.1-2, 10.4 

I/O 10.4 
uses-clause 8.1, 9.1.1-2, 9.2, 9.3 

syntax 8.1 



value parameter 7.3.1 
v/ariable 4 

variable parameter 7.3.2, A 
variable-declaration 4 . 1 

syntax 4.1 
variable-declaration-part 2 . 1 

syntax 2.1 
variable- identifier 4 . i 

syntax 4.1 
varistole-reference 4.2 

syntax 4.1 
variant 3.2.2 

records, new procedure 11.2.1 

syntax 3.2.2 
variant-part 3.2.2 

syntax 3.2.2 
vertical retrace F.3 
VHSelect data type E.3.2 
ViewAngle procedure E.12. 4.1 
viewing pyramid E.12 
Viewport procechjre E.12. 4.1 
visRgn E.5 
Volume function F.4 
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wedges, graphic operations E.9.10 
while-statement 6.2.3.2 

qatimization 12.4 

syntax 6.2.3.2 
with-statement 6.2.4 

syntax 6.2.4 
wordstream tyf» A 
write procedure 10.3.3, A 

with real values D 
write-protection of file 10.1.5 
writeln procedure 10.3.4, A 
xForm matrix E.12 
XorRgn procedure E.9.11 
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H&i procedure E.12.4.2 
zero, signed 3.1.1.3 



CHARACTERS 

$C conpiler cxxunands 12.1 
$0 coflfiiler commands 12.1 
SOECL conpiler command 12.2.1 
$E compiler command 12.1 
$ELSEC conpiler command 12.2.4 
$ENOC conpiler conmand 12.2.4 
$1 compiler command 12.1 
$IFC compiler command 12.2.4 
$L compiler commaids 12.1 
$R compiler conmands 3.1.3, 12.1 
$S compiler command 8.3, 9.1, 9.2, 

12.1 
$SETC compiler command 12.2.1 
$U compiler commands 9.1.2, 9.2.2, 

12.1 
$X compiler commands 12.1 
0, signed 3,1.1.3 
16-bit integer arithmetic 3.1.1.1-2, 

11.3.3 
32-Dlt integer arithmetic 3,1.1.2, 

11.3.3 
30 graphics. See Graf 30. 
a operator 3.3, 5.1.6 
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Pascal Reference h'lanual Mail-B^k Form 



Apple puDllcatlons would like to learn about readers and what you think about this 
manual In order to make better manuals in the future. Please fill out this form, or 
write all over it^ and send It to us. We promise to read it. 

How are you using this manual? 

[ ] learning to use the product [ ] reference [ ] both reference and learning 

[ ) other 

Is It quick and easy to find the infomnatlon you need in this manual? 
[ ] always [ ] often [ ] sometimes [ ] seldom [ ] never 

Comments 

What makes this manual easy to use? 



What makes this manual hard to use? 



What do you like most about the manual?. 



What do you like least about the manual?. 



Please comment on, for example, accuracy, level of detail, number and usefulness of 
examples, length or brevity of explanation, style, use of graphics, usefulness of the 
index, organization, suitability to your particular needs, readability. 



What languages do you use on your Lisa? (check each) 

[] Pascal [] BASIC [] COBOL [ 3 other 

How long have you been programming? 



[ ] 0-1 years [ ] 1-3 [ ] 4-7 [ ] over 7 [ ] not a programmer 

What is your job title? 

Have you completed: 

[ 3 high school [ ] some college [ ] BA/BS [ ] MA/MS [ ] more 

What magazines do you read? 



other comments (please attach more sheets if necessary). 
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